Owner credential renewal (Phase 2b contract)

Status: CONTRACT. Nothing on this page is built. It is the exact interface that the parts of Phase 2b are built against, after the Phase 2a contract (Owner supervisor protocol) and the Phase 3 contract (Live files protocol), both merged and live on development. Every claim about today's code carries a file:line reference into origin/develop at the time of writing; every statement about the proposal is the contract; a guess is labelled ASSUMPTION; a place where the earlier design is wrong or silent is labelled FLAG and listed in section 2. The wire schemas are in section 5 as the code Part P0 adds to host-protocol/src/supervisor.ts. The behavior is in the draft features/computer_owner_credential_renewal.feature (not in features/cucumber-features.txt). The questions this page first left to the owner were answered; the answers are recorded as decisions in section 20 and applied throughout. Where this page and a section of Long-lived computer disagree, this page wins.

1. What Phase 2b is

Today an owner lives at most 50 minutes, because every credential it holds lasts one hour and nothing renews any of them. The control plane drains it at 3000 seconds, the owner finishes or ends its turn within 300 seconds, publishes within 120 seconds and stops, and the next message pays a cold start. Phase 2b lets one owner live up to eight hours by renewing its credentials in place, and keeps every property that made the one-hour window safe: no credential lives longer than an hour, the shell never sees any, and the control plane can end an owner by refusing its next renewal.

owner life (seconds after the bootstrap exchange)
0        2400       4800        7200  ...  26400        28200       28500     28620     28800
|---------|----------|-----------|-----------|-------------|-----------|---------|---------|
bootstrap  renew 1    renew 2     renew 3     renew 11      drain       watchdog  watchdog  hard
(set C0)   (set C1)   (set C2)    (set C3)    (set C11)     (lifetime)  TERM      KILL      end

C0 ends at 3600; C1 at 6000; C2 at 8400; ... C11 at 28800 (3600 would be 30000: the broker caps it at the hard end)
every renewal is asked for when 1200 seconds of the current set are left (40 minutes into its hour)
no renewal after 27900; the 12th would have been at 28800

Pieces, with what is new in bold:

Supervisor (root)
  holds in memory only: supervisor token, supervisor AWS credentials, the active turn's credentials
  **renews the first two every 2400 seconds, the third every 2400 seconds of the dispatch**
  **serves the active turn's credentials to its child over /run/chatticus/supervisor.sock**
    |
    `-- owner.mjs turn (root, one per turn)
          **env: no AWS key, no token. Reads them from the socket whenever the SDK asks.**

Front Door   **POST /host/owner/credentials: refuses unless the owner is the live owner, not draining, not stopping**
Broker       **new purpose supervisor_renewal; every credential it issues ends by the owner's hard end (8 h)**

1.1 What is live today (verified)

1.2 Out of Phase 2b

2. Where the existing design is wrong or silent

Each row is something the earlier text says or leaves open that the live code contradicts or that must be decided before anything is built. The right-hand column is where this page settles it.

3. Decisions

4. Constants

All in host-protocol/src/supervisor.ts. Nothing is read from the environment except where noted. Values that change are marked; the others exist and are listed because the arithmetic uses them.

Declaration order in the file changes: OWNER_DRAIN_GRACE_SECONDS and OWNER_FINAL_PUBLISH_BUDGET_SECONDS must be declared before the constants derived from them.

The arithmetic, for credentials that end at E (the minimum of the AWS expiration and the token expiry):

E <= hard end always, because the broker never issues past it (section 7). At the hard end itself the last set ends at 28800 (renewal 11 at 26400 is capped), the drain is by lifetime at 28200 and by credentials at 28200 as well, the watchdog terminates at 28500 and kills at 28620, all before 28800. The watchdog's clock starts at the supervisor's first action, which is up to 120 seconds (the bootstrap retry window) before the bootstrap exchange; in that worst case it terminates at 28380, inside the drain grace, which is the same graceful path as SIGTERM.

5. Wire schemas

The code below is what Part P0 adds to host-protocol/src/supervisor.ts, with a test of every schema in conversation/test/owner-supervisor-protocol-schema.test.ts. Names not shown are unchanged. The block shows the final state: P0 adds the new names and leaves OWNER_MAX_LIFETIME_SECONDS at 3000 and OWNER_PROTOCOL_VERSION at 2; Part A1 replaces the lifetime with the formula, and Part C raises the version (section 17).

/** Seconds after the bootstrap exchange at which nothing the owner holds is valid: no token, no credential. Eight hours. */
export const OWNER_HARD_LIFETIME_SECONDS = 28800;

/** Seconds of a margin the stop sequence keeps before credentials end. */
export const OWNER_LIFETIME_MARGIN_SECONDS = 180;

/** Seconds before the end of the credentials at which an owner must be draining: the grace, the final publish and a margin. */
export const OWNER_CREDENTIAL_DRAIN_BUDGET_SECONDS = OWNER_DRAIN_GRACE_SECONDS + OWNER_FINAL_PUBLISH_BUDGET_SECONDS + OWNER_LIFETIME_MARGIN_SECONDS;

/** Seconds from the bootstrap exchange until the control plane drains an owner whose credentials were renewed all the way. */
export const OWNER_MAX_LIFETIME_SECONDS = OWNER_HARD_LIFETIME_SECONDS - OWNER_CREDENTIAL_DRAIN_BUDGET_SECONDS;

/** The shortest session STS issues; the broker issues nothing in the last this many seconds of the hard lifetime. */
export const OWNER_BROKER_MINIMUM_SESSION_SECONDS = 900;

/** Seconds after the bootstrap exchange from which no renewal is granted and no dispatch is offered. */
export const OWNER_ISSUANCE_CUTOFF_SECONDS = OWNER_HARD_LIFETIME_SECONDS - OWNER_BROKER_MINIMUM_SESSION_SECONDS;

/** Seconds of remaining credentials at which the supervisor starts asking for new ones. */
export const OWNER_CREDENTIAL_RENEWAL_MARGIN_SECONDS = 1200;

/** Seconds that must pass between two renewals of the same kind for one owner. */
export const OWNER_CREDENTIAL_RENEWAL_MINIMUM_INTERVAL_SECONDS = 60;

/** Pauses, in seconds, between the attempts of a renewal that fails; the last repeats. */
export const OWNER_CREDENTIAL_RENEWAL_RETRY_SECONDS = [15, 30, 60] as const;

/** Seconds before its credentials end at which a supervisor kills everything and exits. */
export const OWNER_CREDENTIAL_HARD_DEADLINE_MARGIN_SECONDS = 30;

/** Where the supervisor listens for its child. A filesystem socket inside a directory only root can enter. */
export const OWNER_SUPERVISOR_SOCKET_PATH = "/run/chatticus/supervisor.sock";

The supervisor token gains one claim (strict schema, so it is required):

export const computerOwnerTokenClaimsSchema = z
	.object({
		audience: z.literal(COMPUTER_OWNER_AUDIENCE),
		tenantId: identifier,
		computerId: identifier,
		ownerId: identifier,
		startGeneration: generation,
		/** When the owner's bootstrap exchange was granted, in seconds since the epoch; every renewal keeps it, and the broker ends every credential by this plus the hard lifetime. */
		ownerStartedAtSeconds: z.number().int().positive(),
		issuedAtSeconds: z.number().int().nonnegative(),
		expiresAtSeconds: z.number().int().positive(),
	})
	.strict();

Error codes and statuses:

// ownerErrorCodeSchema gains:
"owner_draining",     // 409: the control plane is draining this owner, or the issuance cutoff passed. Final.
"owner_stopping",     // 409: a stop was approved. Final.
"renewal_too_soon",   // 429: the same kind was renewed within OWNER_CREDENTIAL_RENEWAL_MINIMUM_INTERVAL_SECONDS.
"turn_not_served",    // 409: the dispatch or the turn is not the one this owner is serving.

// OWNER_ERROR_STATUS gains the four entries, and its value type becomes 401 | 403 | 409 | 422 | 429 | 503.

The route:

/** POST /orgs/{tenant}/host/owner/credentials: the supervisor asks for the next set of credentials, its own or its turn's. */
export const ownerCredentialsRequestSchema = z.discriminatedUnion("kind", [
	z.object({ kind: z.literal("supervisor"), owner_id: identifier, generation }).strict(),
	z
		.object({ kind: z.literal("turn"), owner_id: identifier, generation, dispatch_id: identifier, turn_id: identifier })
		.strict(),
]);

/** The next set. Both kinds end their token and their credentials at the same moment, never later than the owner's hard end. */
export const ownerCredentialsResponseSchema = z.discriminatedUnion("kind", [
	z.object({
		kind: z.literal("supervisor"),
		supervisor_token: z.string().min(1),
		supervisor_token_expires_at: timestamp,
		aws_credentials: awsCredentialsSchema,
	}),
	z.object({
		kind: z.literal("turn"),
		dispatch_id: identifier,
		turn_id: identifier,
		gateway_token: z.string().min(1),
		aws_credentials: awsCredentialsSchema,
		expires_at: timestamp,
	}),
]);

/** A stop reason for an owner that could not renew its credentials: always approved, whatever is pending. */
export const ownerStopReasonSchema = z.enum(["idle", "lifetime", "unhealthy", "credentials"]);

The broker (section 7):

// ownerCredentialBrokerRequestSchema gains a third purpose, same fields as "supervisor", whose authorization is the SUPERVISOR token:
z.object({ ...brokerBase, purpose: z.literal("supervisor_renewal") }).strict(),

// ownerCredentialBrokerResponseSchema gains the matching success:
z.object({
	ok: z.literal(true),
	purpose: z.literal("supervisor_renewal"),
	aws_credentials: awsCredentialsSchema,
	supervisor_token: z.string().min(1),
	supervisor_token_expires_at: timestamp,
}),

// ownerCredentialBrokerErrorCodeSchema gains:
"owner_lifetime_over",   // the owner's hard end is less than OWNER_BROKER_MINIMUM_SESSION_SECONDS away, or past

The local socket (newline-delimited JSON, one request and one answer per connection, a request of at most 1 KiB and an answer the child reads up to 16 KiB of):

/** What the per-turn child asks its supervisor for over the socket. The dispatch id is the one in its environment. */
export const ownerSocketRequestSchema = z.object({ v: z.literal(1), op: z.literal("turn_credentials"), dispatch_id: identifier }).strict();

export const ownerSocketResponseSchema = z.union([
	z.object({ ok: z.literal(true), aws_credentials: awsCredentialsSchema, gateway_token: z.string().min(1), expires_at: timestamp }),
	z.object({ ok: z.literal(false), code: z.enum(["no_turn", "expired"]) }),
]);

no_turn: the dispatch is not the one being served (or none is). expired: the supervisor holds credentials for it but they are past their end because renewals failed. Neither carries a secret.

The child's environment lists change (R10):

// OWNER_CHILD_ENVIRONMENT_NAMES: remove CHATTICUS_MODEL_GATEWAY_TOKEN, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN; add CHATTICUS_SUPERVISOR_SOCKET.
// OWNER_CHILD_FORBIDDEN_ENVIRONMENT_NAMES: add CHATTICUS_MODEL_GATEWAY_TOKEN, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, AWS_CONTAINER_CREDENTIALS_RELATIVE_URI.

6. The control plane

6.1 Route and authentication

The route joins OWNER_COMPUTER_ROUTES (owner-host-auth.ts:27-37) and is declared with audience computer-owner. Its authentication is step 1 to 7 of 5.1 of the 2a contract, unchanged: the token must be unexpired (a renewal needs a token that is still valid, so an owner that let its token lapse is gone), minted for the organization of the path, and the owner it names must be the live owner of the current generation. The stopped replay of 5.1 step 6 is not extended to this route (authenticateOwnerHostRequest allows it for POST /computer/state only, owner-host-auth.ts:190-197); a scenario pins it.

6.2 Handler order

After authentication:

1. Validate the body (422 invalid_request). owner_id and generation equal the token's (403 credential_mismatch).
2. Read the computer record; it must still name this owner (403 not_current_owner, as requireLiveComputer).
3. Lifecycle. ownerStopApprovedAt set: 409 owner_stopping.
   • kind: supervisor: ownerDrainReason(computer, now) is not null, or now - ownerStartedAt >= OWNER_ISSUANCE_CUTOFF_SECONDS: 409 owner_draining.
   • kind: turn: the cutoff applies the same way (409 owner_draining); a drain does not refuse a turn renewal (a draining owner is finishing its turn inside the grace and its child needs credentials until it ends). The dispatch must be the stored one (dispatch_id equals dispatchId, turn_id equals dispatchTurnId), and its turn must be active, claimedBy this owner, with an unexpired attempt lease; else 409 turn_not_served.
4. Rate limit. ownerCredentialsRenewedAt (supervisor) or dispatchCredentialsRenewedAt (turn) newer than now - OWNER_CREDENTIAL_RENEWAL_MINIMUM_INTERVAL_SECONDS: 429 renewal_too_soon. The broker is not asked.
5. Ask the broker: supervisor_renewal with authorization = the presented supervisor token, or turn with the turn's bot and channel from the turn record and the same authorization. OwnerCredentialBrokerError with owner_lifetime_over is 409 owner_draining; any other broker failure is 503 credentials_unavailable. Nothing is recorded, so the owner may ask again at once (the rate limit counts only recorded grants).
6. Record with one conditional update (renewOwnerCredentials, section 6.3): the owner is still live, no stop is approved, and the renewal attribute still has the value read in step 4. A failed condition discards the grant unseen: 409 owner_stopping if a stop was approved meanwhile, 403 not_current_owner if the owner ended or was replaced meanwhile, 409 turn_not_served (turn kind) if a new dispatch replaced the one named, otherwise 429 renewal_too_soon. The owner_credentials_refresh_failed Front Door line records the broker's code when the broker could not serve. For supervisor the update also sets ownerCredentialsExpireAt to min(aws_credentials.expires_at, supervisor_token_expires_at).
7. Respond 200. Log owner_credentials_refresh_ok (section 13).

Mint-then-record is the order of the bootstrap exchange (5.2 step 8 of the 2a contract) for the same reason: a renewal that loses a race costs one STS call and delivers nothing.

6.3 Records

Computer (store/codecs/computer.ts) gains optional fields, cleared with ownerId (setComputerStopped(true), settleLostComputerHost, claimHostStartGeneration) and overwritten at the bootstrap consume:

Store changes: consumeOwnerBootstrap takes credentialsExpireAt; renewOwnerCredentials(tenantId, ownerId, generation, change) where change is { kind: "supervisor"; seenRenewedAt: Date | null; renewedAt: Date; credentialsExpireAt: Date } or { kind: "turn"; dispatchId: string; seenRenewedAt: Date | null; renewedAt: Date }, true when it applied. Condition: owner_id = :o AND owner_generation = :g AND attribute_not_exists(owner_stop_approved_at) AND (attribute_not_exists(<renewed attribute>) OR <renewed attribute> = :seen) and, for a turn, dispatch_id = :d. The per-turn role's MessagingWritable statement still allows the computer record (owner-role-policy.json:50); these fields are written by the Front Door.

6.4 The drain, derived

Replaces ownerLifetimeIsOver (owner-supervisor.ts:180). The reasons are the strings of drain_reason:

export type OwnerDrainReason = "protocol_version" | "lifetime" | "credentials";

export function ownerDrainReason(computer: Computer, now: Date, minimumProtocolVersion: number): OwnerDrainReason | null {
	if (computer.ownerProtocolVersion !== undefined && computer.ownerProtocolVersion < minimumProtocolVersion) return "protocol_version";
	if (computer.ownerStartedAt !== undefined && secondsBetween(now, computer.ownerStartedAt) >= OWNER_MAX_LIFETIME_SECONDS) return "lifetime";
	if (computer.ownerCredentialsExpireAt !== undefined && secondsBetween(computer.ownerCredentialsExpireAt, now) <= OWNER_CREDENTIAL_DRAIN_BUDGET_SECONDS) return "credentials";
	return null;
}

export function ownerIssuanceClosed(computer: Computer, now: Date): boolean {
	return computer.ownerStartedAt !== undefined && secondsBetween(now, computer.ownerStartedAt) >= OWNER_ISSUANCE_CUTOFF_SECONDS;
}

minimumProtocolVersion is a dependency of pollOwner (default OWNER_MINIMUM_PROTOCOL_VERSION) so a scenario can raise it. The reasons are ordered as written; a drain never reverses (the inputs only move one way once the owner is not renewed, and a renewal is refused once any reason holds).

What uses it:

• Poll (step 5 of 5.3 of the 2a contract): drain = ownerDrainReason(...) !== null; drain_reason is the reason. Dispatch (step 6) additionally requires !ownerIssuanceClosed(computer, now): in the last 900 seconds nothing is offered, because the broker would refuse. The server logs owner_dispatch_withheld reason=issuance_cutoff once per owner, not per poll.
• Stop request lifetime: approved when ownerDrainReason(...) !== null, whatever the reason (the stop reason names the order, not the cause; a 2a supervisor that is told drain_reason: "credentials" is an unknown string to it and drains all the same, supervisor.ts:429). credentials and unhealthy: always approved.
• owner_overdue: on a poll, if now - ownerStartedAt >= OWNER_HARD_LIFETIME_SECONDS, one log line per poll with the age. A metric filter alarms on it (section 13).

For an owner that never renews (an image of Phase 2a), ownerCredentialsExpireAt is the bootstrap grant's expiry, about 3600 seconds after the consume, so it is drained at about 3000 seconds exactly as before. Existing scenarios stay green if their steps set ownerCredentialsExpireAt where they set ownerStartedAt (section 21).

6.5 Protocol-version drain

The 2a poll logs owner_protocol_version_low; that line is replaced by the drain above. A drained owner is offered no dispatch (the existing refinement of ownerPollResponseSchema), finishes its turn inside the grace, publishes and stops. The minimum stayed 1 when this landed (R17) and is 3 after the live proof (section 19.1). An owner below the minimum is not refused at the bootstrap: the bootstrap stores the version it announced, and the next poll is answered with drain: true, drain_reason: "protocol_version" and no dispatch.

7. The credential broker

Changes to conversation/src/lambdas/owner-credential-broker.ts (section 7 of the 2a contract is otherwise unchanged):

The role, the absence of a session policy and the fixed ARNs are unchanged. No credential the broker issues ends after the hard end, because the duration is cut to it and refused when it would be shorter than STS allows. The broker still reads no store; it cannot tell whether the owner is superseded, stopping or draining. The Front Door tells it by not asking (6.2 step 3), and the signed anchor bounds a Front Door fault (R7, R8). It still never logs a token, a key or a credential; its lines gain purpose: supervisor_renewal and duration_seconds.

The Front Door's port (conversation/src/computer/owner-credential-broker.ts) gains the overload for supervisor_renewal returning SupervisorGrant; FakeOwnerCredentialBroker handles the purpose, enforces the same hard end, records every request and can hold an answer until a step releases it.

7.1 AssumeRole chaining

STS caps a role session obtained by assuming a role with credentials that are themselves an assumed-role session at one hour ("role chaining"). The broker's own credentials are its Lambda execution role, so its AssumeRole of the two owner roles is the first hop, and the roles' maxSessionDuration (3600, computer-host-start.ts:26) is what limits it today. Phase 2b does not depend on either fact being different:

• Every credential issued is at most 3600 seconds. A longer session is not needed because renewal exists, and it is not wanted: an IAM role session cannot be revoked for one tenant (the only revocation is a deny on aws:TokenIssueTime attached to the role, which hits every tenant). Renewal is what makes "stop the owner" mean "its credentials are gone within the hour".
• The supervisor and the child never call STS. If the supervisor assumed the per-turn role itself it would be chaining (an hour at most) and its role would need sts:AssumeRole, which would let a leaked supervisor credential mint turn credentials. They ask the Front Door, which asks the broker.
• ASSUMPTION A1: whether a Lambda execution role's AssumeRole is treated as chained is not verified here and not needed.

8. The container

8.1 Holders and the atomic swap

/** The credentials one holder serves right now. Replaced as a whole; never mutated. */
export class CredentialHolder<T extends { readonly expires_at: string }> {
	current(): T;
	replace(next: T): void;
}

• AWS credentials. openDisk receives the provider, not a value: openDisk(credentials: () => Promise<AwsCredentialIdentity>) and supervisor-main.ts builds new S3Client({ credentials: provider }) once. The S3SnapshotStore and the S3OverlayBlobReader share that client. The provider returns the holder's current credentials with their expiration and throws only when they are past their end (F9).
• Token. OwnerSupervisorClient gains replaceBearerToken(token); the next request reads it. The SupervisorPlane port declares it too, so the supervisor can call it in the same synchronous step as the credentials; the type of the provider is StorageCredentialsProvider in supervisor-ports.ts.
• The swap. On a renewal answer, in one synchronous function: parse the whole body with ownerCredentialsResponseSchema (done by the client), check kind matches what was asked and the new expiry is later than the held one, then replace the credentials, replace the token, set the new expiry and state, log. No await inside, so the event loop cannot interleave a request between the two replacements.
• What is in flight. A request signs when it starts. A multipart upload (putPack sends CreateMultipartUpload, each UploadPart and CompleteMultipartUpload as separate requests) may straddle the swap: its parts are signed by whichever credentials are current when each starts, and the principal is the same assumed-role ARN (R20). A hydrate (one GetObject stream) or a single PutObject that began before the swap finishes with the credentials it began with (ASSUMPTION A4: S3 authorizes at the start of a request; if it did not, the publish fails, is logged, and is retried at the next trigger as any publish failure is). The SDK adopts the new credentials no later than 5 minutes before the old ones end (F9); the renewal runs 20 minutes before, so there are 15 minutes in which the old credentials are still valid and the new ones are held.
• The first hydrate runs within the first minutes after the bootstrap; renewals begin at 40 minutes. They do not meet.

8.2 The renewal loop

A CredentialLease (one for the supervisor, one for the active turn) has expiresAtMilliseconds, a single in-flight request, and consecutiveFailures. The supervisor's loop gains deadlines (waitForNextEvent) and one step in doDueWork:

• Due when expiresAt - now <= 1200 s, no request is in flight, the next attempt time has come (never less than 60 seconds after the previous success, the server's own limit), and the supervisor is not stopping (R21). The request is started with void and a .finally that wakes the loop, like clearInFlight (supervisor.ts:139,502-507). It runs concurrently with polls and with file operations.
• On success: swap (8.1), reset consecutiveFailures, log owner_credentials_refreshed.
• On failure: consecutiveFailures += 1, log owner_credentials_refresh_failed, next attempt after OWNER_CREDENTIAL_RENEWAL_RETRY_SECONDS[min(failures, 3) - 1] seconds. Within the 600 seconds before the drain that is about twelve attempts.
• The request carries the supervisor token and X-Chatticus-Host-User-Id like every owner request, and the 10 second timeout of the client (protocol-client.ts requestTimeoutMilliseconds).
• Refusals: section 10.

8.3 The socket and the child

The supervisor creates the socket after it has made and locked the directory (supervisor-main.ts:79-80), sets the file to mode 0600 as soon as it is bound (the runtime directory keeps every other user out in the instant before; a umask around listen is not used because Node refuses to set it in a worker thread, where the behavior scenarios run) and refuses to serve on a file with any other mode, removes a stale socket first, and removes it at exit. It serves connections only while a child runs (a connection while none runs is closed unread), at most four at once, one newline-terminated JSON request of at most 1 KiB per connection, answers once, and closes. The answer is not held to 1 KiB: a session token and a gateway token together can exceed it, so the child reads up to 16 KiB. A request that does not parse, or names another dispatch, is answered no_turn. Each request is logged (owner_credential_socket: op, outcome, never a value).

The child:

• Builds new DynamoDBClient({ credentials: provider }) and new S3Client({ credentials: provider }) in createContainerOwnerDeps, with provider asking the socket (SupervisorSocketClient). The identity it returns has the real expiration, so the SDK asks again 5 minutes before the end and gets whatever the supervisor holds then.
• Replaces ModelGatewayConfig.token with tokenProvider. The token is applied per HTTP request in a fetch wrapper (owner-models.ts already has one, timedSender, that wraps every request but only when a logger is given; the wrapper becomes unconditional and sets Authorization). It does not rely on the Pi provider calling resolve for every request (ASSUMPTION A3); resolve returns a placeholder.
• Reads no credential from its environment (R10) and never uses the default chain: a guard test greps the child bundle's sources for AWS client construction without credentials and for the container credentials endpoint and the metadata service.
• On no_turn or expired the provider throws; the request fails, the turn ends with an error (exit code 70, a failure that counts toward the limit of three), and the 2a lost-owner recovery settles the turn (9.3 of the 2a contract). It never falls back to anything.

8.4 A turn longer than an hour

The dispatch carries credentials and a gateway token that end at expires_at (one hour). The supervisor keeps them in a TurnCredentialLease, renews them at expires_at - 1200 with kind: "turn" (the dispatch id and turn id it is serving), and drops the lease when the child exits. The renewal asks the Front Door, which asks the broker with the supervisor token as authorization; the broker mints the same role with the same five tags for the same turn. The gateway then sees a token it accepts for the same turnId, ownerId and startGeneration (model-gateway.ts:331-339), so its check that this owner holds the claim is unchanged. A turn can therefore run until the owner drains: at most 28200 seconds, after which the 300 second grace applies as for any drain. Decided (P1): the grace stays 300 seconds; a turn cut off at the cap is recovered by the next owner through the lost-owner recovery of 9.3 of the 2a contract. The alternative of one long credential for the child is rejected in 7.1: it cannot be revoked and would be eight hours of write access to one conversation.

8.5 Self-stop and the hard deadline

The supervisor keeps E, the end of its credentials (the minimum of the credential expiry and the token expiry as last received).

Exit code 9 joins the list (SUPERVISOR_EXIT_CREDENTIALS_EXPIRED). The 2a constant CREDENTIAL_STOP_MARGIN_MILLISECONDS and credentialsStopAtMilliseconds (a single value) are replaced by the lease. The watchdog is unchanged in logic and changes its two numbers (28500, 28620); the stale-liveness rule is unchanged.

8.6 What the supervisor does not do

It does not renew while stopping (R21), does not renew a draining owner's own credentials (the server refuses with owner_draining, which ends the attempts), does not keep a lease for a turn whose child exited, and never writes a credential to a file, a log or its environment.

9. State machines

9.1 Credentials (the supervisor's, and each turn's)

remaining is E - now.

For a turn the same states apply; expiring there means the child's next storage call may fail and the turn ends as described in 8.3. A turn's credentials are never "refused" except by owner_stopping, because a draining owner is allowed to finish its turn (6.2 step 3).

9.2 The owner's drain reasons

                   ownerDrainReason(computer, now)
protocol below minimum ......................... "protocol_version"   (at the first poll)
now - startedAt >= 28200 ....................... "lifetime"
credentialsExpireAt - now <= 600 ............... "credentials"
otherwise ...................................... none
once any holds: no dispatch, no supervisor renewal, stop(lifetime|credentials|unhealthy) approved

Owner states and exit codes of the 2a contract (10.1) are unchanged, plus exit code 9.

10. Failure handling

Clock skew. Authority is the server's: the drain, the cutoff, the rate limit and the token's expiry check all use the server clock and the AWS expiration it recorded. The supervisor's clock only schedules (when to ask, when to drain itself, when to give up), against absolute timestamps in the response. The margins (1200, 600, 30 seconds) are minutes against a Fargate task whose clock is synchronized by the Amazon time service (ASSUMPTION A10). The first line of defence is that the server drains an owner on its own clock whether or not the owner's clock agrees; the supervisor's own drain is the backstop, not the plan.

11. How this meets the rest of the system

12. Security

12.1 Credentials, after 2b

12.2 Blast radius, one hour against eight

• A leaked credential alone (the AWS keys without the token): at most one hour, as in 2a, whatever the owner's age. Renewal does not lengthen any single credential, and an attacker cannot extend what the control plane does not issue.
• A leaked token with its credentials, from supervisor memory: the holder can renew for as long as the owner stays the live owner, not stopping and not draining: up to the hard end, eight hours, where 2a gave one. What the window buys is bounded by the owner's own life, not by a clock alone: the legitimate owner stops after 15 idle minutes, a stop ends every renewal at once (403 not_current_owner), and a newer generation does too (403 stale_generation). The credentials already issued still work for up to an hour after that, because a role session cannot be revoked for one tenant (7.1). What they open has not changed: one computer's snapshot prefix, and, by polling as the owner, per-turn credentials for turns that are parked on that computer, one at a time. Decided (S4): accepted. The window of a stolen supervisor token is the owner's life, up to 8 hours, mitigated by refusing renewal once the owner is superseded or stopped.
• Why renewal must be refused after a supersede or a stop: otherwise a replaced or stopped owner, including a zombie that came back from a partition, could mint fresh write credentials for a snapshot prefix that a newer owner now holds, and corrupt its disk. The route authentication refuses first (ownerId and ownerGeneration must be the live ones); the stopped replay exception is for the state route only; the owner_stopping refusal and the conditional record close the race with an approved stop. The residual is unchanged from 2a: credentials issued before the stop live until their end.
• Session-tag integrity. The broker builds the tags only after the authorization's claims equal the payload, and the Front Door builds the payload from the verified token (the path tenant is checked equal to the claims in 5.1 step 3; the body's owner_id and generation are only compared). The trust policy still requires exactly the tags tenant and computer (supervisor) or the five (turn) with the Null and ForAllValues conditions. Renewal passes no new input to any of them. The broker cannot know the current generation; the Front Door's step 5 of 5.1 does, and the broker bounds the rest.
• Replay of old tokens. After a renewal the previous token verifies until its own expiry (R19). It is no more powerful than the new one. A token of a finished owner fails the ownerId check; a bootstrap token is 409; a gateway token is 401 on this route (audience). A captured renewal response needs TLS to be captured.
• An owner on a stale generation cannot renew: hostStartGeneration must equal the token's (5.1 step 5) before any other step runs; the broker is not called.
• What a process running as uid 2000 can and cannot reach. It cannot list or enter /run/chatticus (mode 0700, root), so it cannot open the socket (a filesystem socket, never abstract, never TCP); it cannot read /proc/<pid>/environ of a root process, and no secret is in any argv (the child's arguments are the bundle path and turn); it cannot signal or trace root processes; the supervisor listens on no TCP port. It can still reach the Fargate task metadata endpoint, whose task role is empty (unchanged), and loopback ports of other uid-2000 processes. After 2b the child's environment holds no credential at all, which removes the one place a read of /proc would have mattered. The shell never sees a credential. computer/test_owner_container.sh gains the checks (scenario "The shell cannot reach...").
• What a compromised child can do: read its own turn's credentials over the socket, which it already held. It cannot ask for the supervisor's, for another turn's, or for a renewal.
• The broker widens the Front Door a little more. The Front Door could already obtain turn credentials for any parked turn; it can now obtain supervisor credentials for a computer whose supervisor token it holds. It already held the signing key and could mint such a token, so the new bound (the hard end in the signed claim) is a gain, not a loss.
• Findings of the earlier review: unchanged by 2b, except finding 3 (secrets in task overrides), which Phase 2a closed (the task holds one five-minute, single-use bootstrap token).

12.3 Emergency revocation

A role session is revoked for all tenants at once by a deny on aws:TokenIssueTime older than a time, attached to the role through CDK. Because every owner renews, the cost is one failed request for each live owner; it renews and goes on. Decided (S6): this is written as a runbook, docs/OWNER_CREDENTIAL_REVOCATION.md, by Part R (section 17): what to do when a supervisor or a turn credential leaks (revoke the role session with an inline deny carrying an aws:TokenIssueTime condition, through CDK; stop the task; rotate the signing key), in the order to do it, with the cost and the verification of each step.

13. Observability

All lines use the existing emitter and carry tenant_id and owner_id; none carries a token, a key, a credential or a body. Existing lines are unchanged.

Questions the lines answer in Logs Insights: how many renewals did each owner make and how long did each take (owner_credentials_refreshed by owner_id); how often did an owner stop for credentials (owner_stopping reason=credentials); how old is the oldest live owner (owner_started against owner_stopping).

Recommended alarms (a CDK metric filter and alarm, with the Part B2 change): any owner_overdue; five or more consecutive owner_credentials_refresh_failed for one owner; any owner_stopping reason=credentials_expired. None blocks the build.

14. Cost

ASSUMPTION A9: on-demand prices as in the 2a contract (C13), not re-verified. One owner hour has 1.5 supervisor renewals and at most 1.5 renewals for a turn in progress. Each is one Front Door invocation, one broker invocation (256 MB, a few hundred milliseconds), one STS call (free), two DynamoDB writes and a read. That is well under one thousandth of a cent per owner hour, against 0.07 to 0.7 cents an hour for polling. Eleven renewals in eight hours. A faulty supervisor in a renewal loop is limited to 60 renewals an hour by the rate limit. No new resource exists.

15. IAM, CDK and the real-IAM guard

Roles and policies: no change. ComputerSupervisorRole and ComputerOwnerScopedRole keep their trust (the broker's execution role, the exact tag keys with the Null and ForAllValues:StringEquals aws:TagKeys pair), their permission documents (supervisor-role-policy.json, owner-role-policy.json) and maxSessionDuration 3600. The broker's own role keeps GetSecretValue on the signing key and AssumeRole plus TagSession on the two roles, and nothing else. The Front Door keeps InvokeFunction on the broker. A renewal assumes the same role, with the same tags, as the call that created the first credentials; DurationSeconds between 900 and 3600 is inside the role's limit.

Real-IAM guard (docs/ROLE_ACCESS_GUARD.md; the moto and in-memory stores enforce no IAM, which is the reason this section exists). The manifest lists data-plane request shapes per role. A renewal adds no new shape: the supervisor makes the same S3 requests with newer credentials, the child the same S3 and DynamoDB requests through a provider instead of the environment, and the Front Door's new writes are to the computer record, a Messaging-table access the manifest does not record (ROLE_ACCESS_GUARD.md, "Limits") and which the Front Door already holds. Rows to add: none. Rows that must stay covered by scenarios when the code moves, because the child now builds its clients differently: the existing ownerTurn rows for the Pi sessions, the conversation items and the computer record (the coverage hook records them in the 2b end-to-end scenarios; a request without a row fails the scenario). The post-deploy simulate-role-access.ts --environment development is run before the image moves (section 18); it shows nothing new, and a difference is a defect.

What is not covered by the guard and is covered by the live proof instead: the trust policy and tag conditions on the broker's AssumeRole for a renewal (the manifest simulates data-plane actions; the proof reads CloudTrail), and the behavior of S3 when a multipart upload spans two sessions (A5).

CDK tests (infra/test/computer-owner-stack.test.ts): assert the broker role has no permission beyond the secret and the two role ARNs (no DynamoDB, no S3, no SQS); both roles' trust and maxSessionDuration are unchanged; the development fault switch (R22) sets the broker environment in development and fails synthesis for staging and production (gates G1 and G2), and the staging and production templates hold neither fault variable and do hold CHATTICUS_ENVIRONMENT on the broker.

Structural test (conversation/test/broker-fault-gate.test.ts, vitest: a structure guard, not behavior): the two fault variable names appear in no file under conversation/src or infra/lib except the fault module and the stack's development branch; the broker handler imports the fault module and nothing else reads the variables; and initializing the fault module with each of production, staging, an empty and a missing CHATTICUS_ENVIRONMENT and a fault variable set throws (gate G3), while the same with development does not. The scenario "The broker refuses to start with a fault switch outside development" pins the same behavior through the deployed entry point.

16. Traceability

Scenario names are those of features/computer_owner_credential_renewal.feature. Tags: @server, @broker, @supervisor, @child, @image, @infra, @end-to-end.

Scenarios of the design document's Phase 2 list that this closes: "refresh extends credentials and is refused for a stale generation or a stopped computer" (CR1 to CR3), "old protocol drains" (CR11).

17. Work assignment

Nine parts (eight of code, one runbook), each a pull request into develop with Gherkin first (AGENTS.md): the scenarios a part owns move from the draft feature into features/cucumber-features.txt together with their steps, in the same pull request. Each part lists the files it changes. Do not read or write project/. The Kanbus sub-tasks of chatticus-3a31bb carry the same text:

P0. Foundation (first; small; merged before any other part)

Shared contracts only, so that A1, A2, B1, C and D can be built in parallel against them. Its merge deploys the strict claim: see section 18 step 1.

• host-protocol/src/supervisor.ts: every new constant of section 4 (no value changes yet), the schemas of section 5 (claim ownerStartedAtSeconds, the credentials route, the broker purpose and error code, the four error codes and the 429 status, the stop reason credentials, the socket schemas), the child environment list changes. OWNER_PROTOCOL_VERSION, OWNER_MAX_LIFETIME_SECONDS and the derived watchdog constants keep their values until A1 and C.
• conversation/test/owner-supervisor-protocol-schema.test.ts: a test of every new schema, the claim's strictness, the constants' arithmetic (600, 27900, 28200 when A1 lands).
• Every place that mints a supervisor token supplies the claim: conversation/src/lambdas/owner-credential-broker.ts (bootstrap sets ownerStartedAtSeconds to its own nowSeconds; renewal and clamp wait for B1), conversation/features-support/fakes/fake-owner-credential-broker.ts, the steps that mint tokens (owner-host-token.steps.ts and the others the compiler finds), conversation/test/session-token.test.ts, supervisor-session-token.test.ts, fake-owner-credential-broker.test.ts, lambda-owner-credential-broker.test.ts.
• conversation/src/computer/owner-credential-broker.ts: the supervisor_renewal overload and its grant type.
• FakeOwnerCredentialBroker: handles supervisor_renewal, enforces the hard end, records requests, can hold and release an answer, can be told to fail.
• computer/host/src/supervisor-ports.ts: the SupervisorPlane.renewCredentials method and the TurnCredentialSource interface (current(dispatchId): { aws_credentials, gateway_token, expires_at } | null) that D's socket server reads and C's lease implements; conversation/features-support/fakes/fake-supervisor-plane.ts implements renewCredentials (scriptable answers, delays and failures, a record of every request).
• Acceptance: cd conversation && npm run typecheck && npm test && npm run test:features green with no scenario of the draft feature registered; cd infra && npm test.

A1. Server: the drain is derived from the issued credentials (depends on P0)

Behavior-preserving for an image that does not renew; the first part that changes a live number.

• host-protocol/src/supervisor.ts: OWNER_MAX_LIFETIME_SECONDS to 28200 (the formula), the derived watchdog constants.
• computer/chatticus-watchdog: terminate_after=28500, kill_after=28620; the header comment.
• conversation/test/computer-image-structure.test.ts, conversation/features-support/steps/owner-watchdog.steps.ts: the numbers; features/computer_owner_supervisor.feature scenario "The watchdog asks, then forces, at the end of the lifetime" and the new "The watchdog is sized for eight hours" (owned by A1 because it must change with the constants).
• conversation/src/store/codecs/computer.ts, store/messaging-store.ts, store/dynamo-messaging-store.ts, features-support/in-memory-messaging-store.ts: ownerCredentialsExpireAt; consumeOwnerBootstrap stores it; cleared with ownerId. Contract test in conversation/test/dynamo-messaging-store.contract.test.ts.
• conversation/src/domain/owner-supervisor.ts: ownerDrainReason, ownerIssuanceClosed; the poll, the dispatch gate, the stop predicate (lifetime approved for any drain reason; credentials always approved), owner_overdue, the minimumProtocolVersion dependency; exchangeOwnerBootstrap passes the grant's expiry.
• Existing scenarios whose steps set ownerStartedAt also set ownerCredentialsExpireAt (features/owner_supervisor_server.feature lines 261, 269; features/computer_owner_long_lived.feature line 91).
• Steps: conversation/features-support/steps/owner-supervisor-server.steps.ts (the clock, "whose credentials were renewed until", "requires protocol version").
• Scenarios owned: the @server scenarios of CR5 ("No dispatch is offered in the last 900 seconds of the hard lifetime"), CR9, CR10, CR11, CR15; @supervisor "The watchdog is sized for eight hours" (CR25).
• Acceptance: typecheck, vitest, test:features; with the old image the observable drain moment is unchanged (3000 seconds).

A2. Server: the credentials route (depends on P0, A1)

• conversation/src/http/owner-host-auth.ts (OWNER_COMPUTER_ROUTES), conversation/src/http/owner-supervisor.ts (ownerCredentialsHandler), conversation/src/http/app.ts (declareRoute, audience computer-owner), 422 and 429 bodies with code.
• conversation/src/domain/owner-supervisor.ts: renewOwnerCredentials (6.2), for both kinds.
• Store: renewOwnerCredentials (conditional update, in the in-memory store and DynamoDB), the two fields, offerOwnerDispatch resets dispatchCredentialsRenewedAt; contract tests.
• conversation/src/computer/owner-credential-broker.ts: the Lambda adapter handles supervisor_renewal.
• conversation/test/route-audience.test.ts.
• Scenarios owned: all other @server scenarios: CR1 to CR4, CR5 ("No renewal is granted..."), CR6, CR7, CR8, CR12, CR13, CR14 (server side). Steps in owner-supervisor-server.steps.ts (shared with A1; whoever merges second rebases).
• Acceptance: as A1; the coverage hook shows no unlisted request.

B1. Broker (depends on P0)

• conversation/src/lambdas/owner-credential-broker.ts: supervisor_renewal (7), the anchor, the hard end, owner_lifetime_over, DurationSeconds and the token expiry cut to the hard end for supervisor_renewal and turn, stable session names.
• conversation/test/owner-credential-broker.test.ts, lambda-owner-credential-broker.test.ts, and the steps conversation/features-support/steps/owner-credential-broker.steps.ts of features/owner_credential_broker.feature extended (the existing scenarios of that file keep their meaning; the claim is added to their answers).
• The broker requires the signed start time (decided S2): a token without ownerStartedAtSeconds fails the strict claims schema and is invalid_authorization, for every purpose.
• Scenarios owned: all @broker scenarios except the three about the development fault switch (B2's).
• Acceptance: typecheck, vitest, test:features; the broker's log lines carry no token.

B2. Infrastructure (depends on P0; the fault switch part depends on B1, the same file)

• infra/test/computer-owner-stack.test.ts: the assertions of section 15 (can merge before B1).
• The development fault switch (R22, decided P4), with its four gates: infra/lib/control-plane-stack.ts reads the CDK context (ownerBrokerFault: none, deny_supervisor_renewal, deny_turn_renewal; ownerBrokerCredentialSeconds: 900 to 3600) only when the environment is development, throws naming the switch for staging or production (G1), emits the two broker variables only in development and always sets CHATTICUS_ENVIRONMENT on the broker (G2). conversation/src/lambdas/owner-credential-broker-faults.ts (new; the only reader of the variables) throws at initialization if a variable is set and CHATTICUS_ENVIRONMENT is not development (G3); owner-credential-broker.ts takes a faults dependency (default none) and applies it: a denied purpose answers assume_role_failed, a shorter duration replaces 3600, never longer and never below 900 (G4). The broker edit is made after B1 merges.
• conversation/test/broker-fault-gate.test.ts: the structural test of section 15.
• The metric filters and alarms of section 13 (optional in the same PR).
• Scenarios owned: both @infra scenarios and the @broker scenario "The broker refuses to start with a fault switch outside development".
• Acceptance: cd infra && npm test; cd conversation && npm test && npm run test:features; npx cdk synth with and without the context in development, and with it for staging and production (fails, naming the switch).

R. Emergency revocation runbook (no code; independent of every other part)

Decided S6. Contract: this page, 12.3 and 7.1.

• docs/OWNER_CREDENTIAL_REVOCATION.md (new): what to do when a supervisor credential or a per-turn credential leaks, in order, each step with its cost, who may do it and how to verify it: (1) stop the task (aws ecs stop-task; the owner reports stopped, the control plane then refuses its token because the owner is no longer the live owner); (2) revoke the role session with an inline deny on ComputerSupervisorRole and ComputerOwnerScopedRole carrying an aws:TokenIssueTime condition (a CDK change deployed by the normal path, never by hand in the console; it affects every tenant's sessions of that role, and live owners recover at their next renewal because a new session has a later issue time); (3) rotate the signing key secret (it invalidates every supervisor, bootstrap and gateway token at once; owners then exit 5 and publish nothing, so it is the last resort and the document says what unpublished work is lost); (4) after the incident, remove the deny, and check CloudTrail AssumeRole events and the owner_credentials_refreshed lines to bound what was reachable. It cites the blast-radius analysis of 12.2 and holds no account id (those live in AGENTS.local.md).
• A link from docs/THREAT_MODEL.md and from this page's 12.3.
• Acceptance: the document exists, every command in it was run read-only or in a dry run on development where that is possible (the CDK deny is synthesized, not deployed), and a second reader followed it once. Kanbus comment with the result.

C. Supervisor (depends on P0; integrates with A2 and B1 in E)

• computer/host/src/supervisor.ts: leases, the renewal activity, the swap, the local drain at E - 600, the hard deadline and exit 9, no renewal while stopping, stop reason credentials; OWNER_PROTOCOL_VERSION to 3 (in host-protocol/src/supervisor.ts). computer/host/src/supervisor-ports.ts: SUPERVISOR_EXIT_CREDENTIALS_EXPIRED = 9.
• computer/host/src/protocol-client.ts (renewCredentials, replaceBearerToken), supervisor-main.ts (the S3 client with a provider; openDisk signature), host-disk-lifecycle.ts if it holds credentials.
• A CredentialHolder and CredentialLease module (new, computer/host/src/credential-lease.ts) with a vitest unit test of the schedule and the swap.
• conversation/test/owner-supervisor-client.test.ts (the client's new method and token replacement).
• The fake plane (fake-supervisor-plane.ts, from P0), the fake spawner (fake-child-spawner.ts: a fake child already runs until told) and a storage fake that records the credentials of each request (fake-supervisor-disk.ts), in conversation/features-support/fakes/; the steps are in conversation/features-support/steps/owner-supervisor-renewal.steps.ts.
• Scenarios owned: the @supervisor scenarios of CR14 (supervisor side), CR16 to CR20, CR24 (not the watchdog scenario, A1's). They live in features/computer_owner_credential_renewal_supervisor.feature, registered in features/cucumber-features.txt; the draft keeps only the socket scenario of D. A scenario that runs past fifteen idle minutes has the control plane veto the idle stop, as it does while work is pending, and the scenario "An owner stops before the credentials it holds expire" of computer_owner_supervisor.feature now has the renewals fail, stops with the reason credentials at 3000 seconds.
• Acceptance: computer_owner_supervisor.feature stays green; typecheck; vitest; the supervisor bundle imports nothing forbidden by computer-image-structure.test.ts.

D. Child and socket (depends on P0; integrates with C in E)

• computer/host/src/supervisor-socket.ts (new): the server (listen under umask 0o177, stale socket removal, limits, schema, no_turn, logs) against the TurnCredentialSource of P0; supervisor-main.ts creates it.
• computer/host/src/supervisor-child-environment.ts: no credentials, adds the socket path; its vitest.
• computer/host/src/owner-deps.ts, owner-models.ts, owner-main.ts: providers, SupervisorSocketClient, the fetch wrapper that sets Authorization, the failure path.
• conversation/test/container-owner-config.test.ts, owner-session-env.test.ts: updated for the missing environment.
• conversation/test/computer-image-structure.test.ts: the guard of 8.3 (no AWS client without credentials, no metadata endpoints) over the child's sources.
• computer/test_owner_container.sh: the shell cannot list /run/chatticus, open the socket, or read the environment of the supervisor or the child.
• Scenarios owned: @child and @image; the socket scenarios of CR20.
• Acceptance: as C; computer/test_owner_container.sh passes against a built image.

E. Integration, deploy and live proof (depends on A1, A2, B1, C, D; B2 for the failure proof)

• The four @end-to-end scenarios in one steps file, with the real routes, the real supervisor and a fake clock.
• conversation/bin/acceptance.ts (and conversation/src/acceptance/): a --owner-soak <minutes> mode (section 19).
• The deploy and the live proof of sections 18 and 19, each result recorded in a Kanbus comment.
• The milestone sub-agent required by AGENTS.md: Kanbus statuses, the README "What is live today", this page's Status block becomes "BUILT", the draft feature file's header is removed as its scenarios are registered.
• Acceptance: all of the above, and docs/LONG_LIVED_COMPUTER.md Phase 2b marked live.

Order and dependencies

P0 --+--> A1 --> A2 ----------+
     +--> B1 --> B2 (switch) -+--> E
     +--> B2 (assertions) ----+
     +--> C -----------------+
     +--> D -----------------+

1. This contract merges. 2. P0 merges (one pull request, reviewed first). 3. A1, B1, B2 (assertions), C, D in parallel; A2 after A1; B2's fault switch after B1. 4. E last. C and D need only the fakes of P0; the integration is E's. Part R has no dependency and no dependent: any time.

18. Deploy order

The Computers stack (the owner task definition) is not touched. Merging to develop deploys the ControlPlane and ThinTurn stacks from CI and builds the image as sha-<commit> without moving the tag the task definition reads (docs/COMPUTER_IMAGE_PROMOTION.md). The image moves only by the separate promotion workflow, after the server side of the same commit is verified. Development only; there is no compatibility path.

1. Before P0 merges: no owner task is running (aws ecs list-tasks on the Computers cluster, from a logged-in shell). P0's broker puts the new claim in every supervisor token it issues, and the strict claims schema refuses a token of the previous format: a running owner would get 401 on its next poll, exit 5 and publish nothing. This is the same precondition as Phase 2a.
2. P0, then A1 and B1 (ControlPlane and ThinTurn deploy from CI). The old image (Phase 2a) still runs: it bootstraps, polls, is dispatched and drains at about 3000 seconds, because the server derives the drain from the credentials it issued (R4). Verify with one message to a development computer: owner_started, owner_bootstrapped, owner_serving_turn, owner_child_exited clean=true.
3. A2 and B2. The route is covered in CI by the scenarios on the real routes (a live owner of the old image never calls it, so nothing on development exercises it until the image moves). Check the deploys succeeded and that the Front Door log shows no owner_* error.
4. C and D merge (the image builds as sha-<commit>, nothing changes in the running system).
5. Run npx tsx conversation/bin/simulate-role-access.ts --environment development (read-only). It must show every manifest row allowed and nothing new (section 15).
6. Run Promote computer image (development) with the full commit sha of C and D. The workflow itself refuses unless the ControlPlane and ThinTurn runs for that commit succeeded.
7. The live proof (section 19).
8. Only after step 7 has passed, and the new image has run in the field, an operator may raise OWNER_MINIMUM_PROTOCOL_VERSION to 3 in a separate change (decided P3). Until then it stays 1. Done: section 19.1.
9. Rolling back: the image first (COMPUTER_IMAGE_PROMOTION.md, "Rolling back"). The server stays: it serves an old image unchanged. Never roll the server back below the promoted image: a supervisor of this phase against a server without the route retries a missing route for 10 minutes, drains itself, and its credentials stop reason is a 422 to the older server.

What breaks between the steps, and only on development: nothing, by construction, other than step 1's precondition. A new image against an old server, and an old image against a new server, are both avoided by the order; the second is also safe.

19. Live proof

Requirement: an owner survives past 50 minutes and past one hour of credentials, a turn survives past one hour of its credentials, a failed renewal ends the owner cleanly, a refused renewal after a stop is observed. Idle computers stop after 900 seconds and run one turn at a time (F13), so each proof states how the owner is kept busy.

Evidence sources. The owner's log stream (awslogs, prefix computer-owner), the Front Door log group, CloudTrail LookupEvents (EventName=AssumeRole, role names ComputerSupervisorRole and ComputerOwnerScopedRole), and GET /computer for the record. Run from a logged-in shell; the commands use AWS_PROFILE as in AGENTS.local.md.

1. Renewal across one hour, with short turns (75 minutes). The acceptance runner mode of Part E, npm run acceptance -- --environment development --owner-soak 75, creates a bot and a channel, and every 8 minutes sends a message whose only job is "append the current time to /workspace/soak.log with a shell command". Eight minutes is under the idle timeout (15), and a turn takes seconds, so the owner is idle and polling between turns. Check:
   • exactly one owner_started, and owner_bootstrapped, for the whole run;
   • owner_credentials_refreshed kind=supervisor at about 40 minutes (+/- 1) and again at about 80 minutes if the run is extended to 85 minutes (extend it once as a final confirmation); remaining_seconds_before about 1200;
   • the turns sent at minutes 64 and 72 are served (owner_child_exited clean=true): the poll that offered them was accepted only because the supervisor presented its renewed token (the first one ended at 60 minutes), and the dispatch credentials they ran with were issued by a broker call authorized by that token. (No kind=turn renewal is expected here: turns are short. That is step 2.)
   • a snapshot_published after minute 61 (the quiet publish after the last turn): it can only succeed with the renewed supervisor credentials; the published checksum in GET /computer changes;
   • CloudTrail: AssumeRole of ComputerSupervisorRole at 0, about 40 and, in the extended run, about 80 minutes, every one by the broker role, tags tenant and computer, RoleSessionName supervisor-<ownerId> all three times;
   • after the run, stop sending; at 15 idle minutes owner_stopping reason=idle and the stopped report (the idle clock was not touched by the renewals); the next message starts a new owner that hydrates soak.log with every line.
2. A turn longer than the first hour of its credentials (about 70 minutes). The same mode with --long-turn: one message asking the bot to run sleep 590 seven times in separate terminal calls and then write done to /workspace/long.log (each tool call ends inside its own 600 second limit). The child is busy for about 69 minutes, so the owner is never idle. Check owner_credentials_refreshed kind=turn at about 40 minutes after the dispatch, the tool calls after minute 60 succeed, the Pi session commit objects written after minute 60 exist, and owner_child_exited clean=true. ASSUMPTION: a model that is asked for seven sleeps does them; if it does not, repeat. A computer runs one turn at a time, so run steps 1 and 2 one after the other, or in two organizations at once if the acceptance runner can create a second one.
3. The same proofs in 15 minutes, with the development fault switch (Part B2). Deploy the development ControlPlane with ownerBrokerCredentialSeconds=900. Supervisor credentials then last 900 seconds, below the 1200 second margin, so the supervisor renews every 60 seconds (the rate limit): in a 20 minute run the original credentials expire at 15 minutes, a publish after that works, and owner_credentials_refreshed appears about 20 times. This proves the swap across a real expiry. Restore the deploy afterwards.
4. Failure of renewal. Deploy with ownerBrokerFault=deny_supervisor_renewal and ownerBrokerCredentialSeconds=900: the owner bootstraps with 900 second credentials, every renewal is a 503, so owner_credentials_refresh_failed repeats at 15, 30, 60 seconds; at 300 seconds after the bootstrap (600 seconds before the 900 second credentials end) owner_draining reason=credentials and owner_credentials_expiring; with a turn running, owner_child_exited at about 600 seconds after the bootstrap (the 300 second grace); owner_stop_requested reason=credentials, owner_stop_decision approved=true, snapshot_published if changed, owner_stopping reason=credentials, the task STOPPED, the record stopped with no owner, the container exit code 0, and the owner gone before 900 seconds. A message sent during the drain parks, and the stopped report starts the next owner. Restore the deploy afterwards.
5. Nothing is renewed after a stop. Send ecs stop-task to an owner at 41 minutes into step 1 (inside its renewal window): owner_stopping reason=sigterm, the stopped report, and, in the broker's log group, no owner_broker_issued purpose=supervisor_renewal for that owner id after the stop. (The refusal itself, 403 not_current_owner and 409 owner_stopping, is proved by the scenarios; a live owner's token is never extracted.)
6. At the end of the 8 hours the owner is not run for eight hours live; the 8-hour behavior is proved by the end-to-end scenario (fake clock) and, live, by step 1 extended past 85 minutes. This is a stated limitation. The 8 hours are measured from the bootstrap (decided P2).

Cost of the proof. Steps 1 and 2 cost model calls for a few dozen small turns and one computer-hour each. Steps 3 and 4 need two ControlPlane deploys.

19.1 Live proof results (development)

Both proofs were run on the development environment against the image that renews.

Success path, 81 minutes. One owner, one task, no self-stop. The supervisor renewed its credentials at minute 40 and again at minute 80, each time with about 1200 seconds remaining (the renewal margin), as in step 1.

Failure path, with the development broker fault (deny_supervisor_renewal, 900 second credentials). The broker answered every renewal 503 credentials_unavailable. The retry pauses were 15, 30 and then 60 seconds. The owner drained when 600 seconds of its credentials remained (owner_draining reason=credentials), asked to stop with the reason credentials, and owner_stopping reason=credentials followed about five minutes after the bootstrap. The next message started a fresh owner.

What the code says, and where the observations need a reason

• The drain begins at expiry minus 600 seconds. OWNER_CREDENTIAL_DRAIN_BUDGET_SECONDS is the drain grace (300) plus the final publish budget (120) plus the lifetime margin (180), which is 600. CredentialLease.localDrainAtMilliseconds() returns the expiry minus that budget, and the supervisor begins its own drain from it (beginCredentialDrainWhenExpiring) without waiting for the control plane. With 900 second credentials that is 300 seconds after the bootstrap. The hard deadline is the expiry minus 30 seconds.
• The first failed renewal comes about 60 seconds after the bootstrap when credentials last 900 seconds. The 1200 second renew-ahead window is longer than the 900 second lifetime, so renewing is already due at the bootstrap. What delays it is the minimum interval: CredentialLease.dueAtMilliseconds() takes the latest of the window start, the last success plus OWNER_CREDENTIAL_RENEWAL_MINIMUM_INTERVAL_SECONDS (60), and, after a failure, the retry pause. The bootstrap counts as the first success, so the first attempt is at 60 seconds. Later attempts follow the 15, 30, 60, 60... pauses because the 60 second floor has already passed.
• Exit codes by cause (computer/host/src/supervisor-ports.ts): 0 for a stop the control plane approved, whatever its reason (idle, lifetime, credentials, unhealthy); 143 for SIGTERM; 9 (SUPERVISOR_EXIT_CREDENTIALS_EXPIRED) when the hard deadline cut a stop short, logged as owner_stopping reason=credentials_expired; 5 when the owner learned it is no longer the owner (owner_stopping reason=superseded); 4 when the control plane fell silent (fenced); 6 bootstrap failed; 7 wrong settings; 8 the disk could not be restored.
• The container exit code 5 and the second owner_stopping reason=superseded line 0.3 seconds after reason=credentials were a bug, not the design. While the approved stop was running, the supervisor kept polling. A poll the control plane answered with an ownership refusal (403 not_current_owner) made the poll failure handler end the owner as superseded: a second owner_stopping line and, because that came before the stopped report returned, exit code 5 instead of 0. The scenario "A poll refused while the owner is stopping does not turn an approved stop into superseded" in features/computer_owner_supervisor.feature reproduces exactly that log and exit code and now passes. A poll refused while the owner is stopping changes nothing; the stopped report decides, and a refused stopped report still ends the owner as superseded. A credentials stop exits 0 from this change on.
• The minimum protocol version is 3. The live owner record reports owner_protocol_version 3, the version that renews (OWNER_PROTOCOL_VERSION in host-protocol/src/supervisor.ts, announced in the bootstrap and every poll, and imported by both the supervisor and the control plane). An owner that announced a lower version is not refused at the bootstrap; its next poll is answered with drain_reason: "protocol_version" and no dispatch. The development image tag already runs the new image; the staging and production images must be built from this code before this change reaches main, or their owners drain on every poll.

20. Decisions taken

Assumptions (marked where they appear):

• A1. A Lambda execution role's AssumeRole is not role chaining. Not needed (7.1).
• A2. The SDK re-reads a provider's credentials only inside the last 5 minutes before their expiration. Read from the installed @smithy/core (memoizeIdentityProvider, EXPIRATION_MS = 300_000); P0 pins the check in a vitest test against the installed version.
• A3. Pi calls resolve for every model request. Not relied on: the gateway token is set by the fetch wrapper.
• A4. S3 authorizes a request when it starts, so a single GetObject or PutObject begun before the credentials end finishes after they end. If not, the failure is a logged publish failure retried at the next trigger. The publish cadence makes this irrelevant while renewals succeed.
• A5. A multipart upload begun with one session of a role may be continued with another session of the same role and the same session name. If S3 refuses, the publish fails once and is retried from the start.
• A6. Fargate keeps /run writable and supports a filesystem Unix socket (the directory already exists and is written).
• A7. /proc/<pid>/environ and /run/chatticus are unreadable to uid 2000 (the existing container test proves the first).
• A8. STS accepts DurationSeconds from 900 to 3600 for these roles.
• A9. Prices (section 14).
• A10. The task clock is synchronized by the platform.

Decisions of the owner. The owner took the recommendations on the questions this page first left open. Each is applied where it matters; the third column says where.

Alternatives that these decisions reject, and that therefore have no scenario here: a longer drain grace (P1), an external watchdog chain (P5), a broker that reads the computer record (S1), a rotating token serial (S3), and renewal bound to recent activity (S4).

Risks.

1. The change to the claims schema and the child's environment touches every place a token is minted and every test that builds a child: P0's compile errors will list them; the plan is to fix them all in P0.
2. The SDK memoization (A2) and the per-request gateway token (A3) are the two places where "the child holds the new credentials" could silently be false; the scenarios "A turn that runs past the first hour keeps working" and "The model gateway token is read for each request" run with a clock that moves past the expiry.
3. The failure path is easy to get subtly wrong because every number is a margin on another. The arithmetic of section 4 is asserted by a vitest test over the constants, and the scenarios use the same constants.
4. A model that is asked to sleep eleven times may not (section 19 step 2).
5. The first hour of every owner that is deployed is exercised by the proof only if the proof is run; the real first renewal happens in the field at 40 minutes. The alarm on owner_credentials_refresh_failed is how a regression shows.

21. What changes in existing tests and files

features/owner_supervisor_server.feature (the two scenarios that move the clock 3000 seconds past the bootstrap: their steps also set ownerCredentialsExpireAt; the "lifetime" stop outline is extended in A1), features/computer_owner_long_lived.feature (the step "the owner was bootstrapped 3000 seconds ago"), features/computer_owner_supervisor.feature (the watchdog and "An owner stops before the credentials it holds expire" scenarios: the latter now describes the lease and stops with the reason credentials), features/owner_credential_broker.feature (the claim in the answers), features/owner_host_token.feature (the claim), features/supervisor_role_policy.feature and features/owner_role_policy.feature (unchanged), conversation/test/session-token.test.ts, owner-supervisor-protocol-schema.test.ts, computer-image-structure.test.ts, container-owner-config.test.ts, owner-session-env.test.ts, route-audience.test.ts, dynamo-messaging-store.contract.test.ts, computer/test_owner_container.sh, and docs/OWNER_SUPERVISOR_PROTOCOL.md sections 1.1, 3, 8 and 13 (the reserved rows, the lifetime constant and the live-proof item 8, which point here). The list is the author's reading of the code; the implementer finds the rest by running the gates.