Live files protocol (Phase 3 contract)

Status: CONTRACT, built in Phase 3 (the "as built" notes under section 15 say where the code differs). It is the exact interface that several people build against in parallel for Phase 3 of Long-lived computer, file protocol and preview: the shared schemas (F0), the server (A1, A2), the container (C) and the web app (W). It builds on the merged and live Owner supervisor protocol (Phase 2a) and on the read-only snapshot file routes of Phase 1. Every claim about today's code carries a file:line or file reference into origin/develop at the time of writing. Every statement about the proposal is the contract; a guess is labelled ASSUMPTION. The wire schemas in section 5 are code to be added in host-protocol/src/live-files.ts and host-protocol/src/live-file-rules.ts by the foundation step F0; until F0 merges, this page is the source. Once it merges, where this page and those files disagree, fix the page. The draft behavior is in features/computer_file_live_member.feature and the other computer_file_*.feature files.

Revision 2 (owner decisions). The owner decided that a computer is needed only to run things, never to view or edit files: a person reads and edits files while the computer is off, an open Files panel neither starts nor keeps awake a computer, and the interactive pace is 1 second. That replaces the first revision's refusal of a write while the computer is off with an edit overlay in the snapshot bucket (sections 3 O1 to O4 and L30 to L47, 5.5, 7.7, 9.4, 11.7, 12.8, 19). Everything else in this page stands unless a section says otherwise.

Revision 3 (owner decisions). Delete, rename and new folders are required in Phase 3, including while the computer is off. The overlay therefore records four kinds of operation (put, delete, mkdir, move), and the owner applies them at hydrate in a defined order (section 7.8; decisions L48 to L66; schemas 5.2 and 5.5; helper operations 8.1). Also settled: non-current bucket versions expire after 30 days (part B, section 12.8), customer-account computers stay read-only for stated reasons (L46) with a later-phase ticket, any enabled member may discard a pending change, and LocalWorkerRole is left as it is.

1. What Phase 3 is

A member of the organization opens the Files panel and sees the files as they are now, and can change a text file. The computer is needed only to run things, never to view or edit files (owner decision O1). Which source answers depends on the computer:

Viewing and editing never start a computer. An open panel does not keep one awake.

Browser (Files panel)
  | GET/PUT/POST /orgs/T/computer/files/...
  v
Front Door Lambda
  | 1. member principal, rate limit, path rules
  | 2. choose the source (7.2): live owner able to serve?  else snapshot + overlay
  | live:    audit first, queue a request in the table (one transaction with the stop guard), wait up to 8 s
  | overlay: audit first, put the blob, compare-and-swap the overlay index in S3 (If-Match)
  v
Messaging table   T#computer#fileops  T#computer#audit              Snapshot bucket  tenants/T/computers/K/
  ^                                                                    snapshot.tar.gz  index/  manifest.json
  | poll response carries file_requests;                               overlay/index.json  overlay/blobs/{sha256}
  | POST /host/owner/file-results carries the answer                      ^           ^
  |                                                                       | reads      | the Front Door alone writes and deletes
Supervisor (root, in the container)  ---- hydrate: extract, seal, apply through the helper, publish, ask to clear
  | spawns, with a timeout and a concurrency of 2
  v
File helper (uid 2000, through chatticus-shell)    list | stat | read(range) | write(atomic, precondition)
  workspace

What does not change: no socket, no inbound port, no new AWS resource. What does change in infrastructure (revision 2): the Front Door role gains PutObject and DeleteObject on the overlay prefix, and the supervisor role gets an explicit deny of writes to that prefix (section 12.8).

1.1 Out of Phase 3 (reserved, nothing implemented)

2. What is wrong or underspecified in the design, given the code now live

The design document is from before Phases 1 and 2a. These are the places where it is wrong, silent or contradicted by origin/develop. Each one is settled by a decision in section 3 (L-numbers) unless it says "open".

3. Decisions made in the contract

3.0 Decisions of the owner (revision 2)

The numbers are this page's own (L1, L2, ...). D8, D9 and D14 of the design are unchanged and used as stated: every enabled organization member reads and writes, the edit is direct with a hash check and an audit record, audit retention is 90 days.

4. Constants

All in host-protocol/src/live-files.ts unless stated. Tests inject clocks; nothing is read from the environment.

Not changed: DEFAULT_HEARTBEAT_TIMEOUT_SECONDS = 30, OWNER_POLL_* tiers, OWNER_IDLE_TIMEOUT_SECONDS, OWNER_POLL_SILENCE_FENCE_SECONDS. The 8 second wait fits inside the 25 second fence only because the wait is in the Front Door, not the owner.

5. Wire schemas

Two new files in host-protocol/ and four small edits to host-protocol/src/supervisor.ts. package.json exports ./live-files and ./live-file-rules. live-file-rules.ts imports nothing at all (the file helper bundle must stay free of zod and of anything that could carry a credential); live-files.ts imports zod and live-file-rules.ts; supervisor.ts imports live-files.ts, never the other way round.

5.1 host-protocol/src/live-file-rules.ts (no imports)

/** The root of every path a person or the Front Door names. */
export const LIVE_WORKSPACE_ROOT = "/workspace";

/** The longest path, in characters, any file route accepts. */
export const LIVE_FILE_PATH_MAX_CHARACTERS = 1024;

export type LivePathProblem = "empty" | "too_long" | "nul" | "not_absolute" | "dot_dot" | "outside_workspace";

/**
 * Why a path is not a workspace path, or null when it is one. Lexical only: it follows no link.
 * The path must be absolute, at most 1024 characters, hold no NUL and no ".." segment, and after
 * normalisation be "/workspace" or start with "/workspace/".
 */
export function livePathProblem(raw: string): LivePathProblem | null;

/** The normalised form ("/workspace/a/b", no trailing slash, no "." segment). Precondition: livePathProblem(raw) === null. */
export function normalizeLivePath(raw: string): string;

/** Whether any segment of a normalised path is exactly ".git" (a file or a directory). */
export function livePathHasGitSegment(normalized: string): boolean;

/**
 * Whether a path looks like it holds a secret. Case-insensitive on the segments. True for a file named .env or .env.*,
 * *.pem, *.key, *.p12, *.pfx, id_rsa*, id_ed25519*, credentials, .netrc, .npmrc, .git-credentials, and for any file under
 * a directory named .ssh or .aws. It is the Phase 1 list plus .git-credentials.
 */
export function looksLikeSecretFile(path: string): boolean;

/** True when the first 8 KiB holds a NUL or is not valid UTF-8. */
export function looksBinary(bytes: Uint8Array): boolean;

/** Drop an incomplete UTF-8 sequence from the end of a byte range. */
export function trimToCharacterBoundary(bytes: Uint8Array): Uint8Array;

/** The number of bytes of the UTF-8 encoding of a string. */
export function utf8ByteLength(text: string): number;

conversation/src/snapshot/files.ts deletes its private copies (indexPathOf keeps its index-path mapping on top of livePathProblem, looksLikeSecretFile, looksBinary, trimToCharacterBoundary) and imports these. That is a behavior-preserving move plus .git-credentials; the existing scenarios in computer_snapshot_index.feature stay green.

5.2 host-protocol/src/live-files.ts

import { z } from "zod";
import { LIVE_FILE_PATH_MAX_CHARACTERS, livePathProblem, utf8ByteLength } from "./live-file-rules.ts";

export const LIVE_FILE_WAIT_MILLISECONDS = 8000;
export const LIVE_FILE_RESULT_CHECK_MILLISECONDS = 250;
export const LIVE_FILE_OUTCOME_GRACE_MILLISECONDS = 7000;
export const LIVE_FILE_OPERATION_TTL_SECONDS = 120;
export const LIVE_FILE_INTERACTIVE_WINDOW_SECONDS = 45;
export const LIVE_FILE_WATCH_INTERVAL_SECONDS = 15;
export const LIVE_FILE_MAX_REQUESTS_PER_POLL = 4;
export const LIVE_FILE_MAX_OPEN_OPERATIONS = 16;
export const LIVE_FILE_MAX_CONCURRENT_HELPERS = 2;
export const LIVE_FILE_MAX_QUEUED_REQUESTS = 8;
export const LIVE_FILE_HELPER_TIMEOUT_MILLISECONDS = 6000;
export const LIVE_FILE_MEMORY_REFUSE_PERCENT = 90;
export const LIVE_FILE_CONTENT_MAX_BYTES = 262144;
export const LIVE_FILE_READ_MAX_FILE_BYTES = 8388608;
export const LIVE_FILE_LISTING_MAX_ENTRIES = 2000;
export const LIVE_FILE_LISTING_SCAN_MAX_NAMES = 20000;
export const LIVE_FILE_TREE_MAX_ENTRIES = 5000;
export const LIVE_FILE_STDOUT_MAX_BYTES = 1048576;
export const LIVE_FILE_RATE_WINDOW_SECONDS = 60;
export const LIVE_FILE_READ_RATE = 240;
export const LIVE_FILE_WRITE_RATE = 30;
export const LIVE_FILE_REVEAL_RATE = 10;
export const LIVE_FILE_WATCH_RATE = 12;
export const LIVE_FILE_AUDIT_RETENTION_DAYS = 90;
export const LIVE_FILE_PENDING_AUDIT_UNKNOWN_SECONDS = 120;
export const LIVE_FILE_RETRY_AFTER_MIN_MILLISECONDS = 1000;
export const LIVE_FILE_RETRY_AFTER_MAX_MILLISECONDS = 10000;

const identifier = z.string().min(1).max(256);
const timestamp = z.iso.datetime();
const generation = z.number().int().positive();
const sha256Hex = z.string().regex(/^[0-9a-f]{64}$/);
const mode = z.string().regex(/^[0-7]{3,4}$/);

/** A path under /workspace, lexically valid. The same rules as livePathProblem; the issue message names the problem. */
export const livePathSchema = z.string().max(LIVE_FILE_PATH_MAX_CHARACTERS).superRefine((value, context) => {
	const problem = livePathProblem(value);
	if (problem !== null) context.addIssue({ code: "custom", message: `not a workspace path: ${problem}` });
});

/** UTF-8 text a person may save: at most 256 KiB, no NUL. */
export const liveFileTextSchema = z.string().refine(
	(text) => utf8ByteLength(text) <= LIVE_FILE_CONTENT_MAX_BYTES && !text.includes("\u0000"),
	{ message: "content must be UTF-8 text of at most 262144 bytes with no NUL" },
);

/** One directory entry, the same shape for a live listing and a snapshot listing. */
export const liveFileEntrySchema = z
	.object({
		name: z.string().min(1).max(255),
		path: livePathSchema,
		kind: z.enum(["file", "directory", "symlink"]),
		size: z.number().int().nonnegative().nullable(),
		mode: mode.nullable(),
		sha256: sha256Hex.nullable(),
		link_target: z.string().max(4096).nullable(),
		modified_at: timestamp.nullable(),
		/** "pending": an overlay change is in effect; "conflict": the person's change conflicts with a newer snapshot (the entry shows theirs). */
		overlay: z.enum(["none", "pending", "conflict"]),
		/** Only on the stat of a directory: its tree hash (L49), the ETag of a delete or rename. */
		tree_sha256: sha256Hex.nullable(),
	})
	.strict();

/** What a write must find on the disk. "if_match" replaces a file with this hash; "if_none_match" creates a file that must not exist. */
export const liveFileWritePreconditionSchema = z.discriminatedUnion("type", [
	z.object({ type: z.literal("if_match"), sha256: sha256Hex }).strict(),
	z.object({ type: z.literal("if_none_match") }).strict(),
]);

/**
 * What a delete or a move must find: the effective hash of the path (L49), which is the content hash of a file, the link hash
 * of a symlink or the tree hash of a directory. The owner decides which it is by what is really at the path.
 */
export const liveFileRemovePreconditionSchema = z.object({ type: z.literal("if_match"), sha256: sha256Hex }).strict();

const requestBase = {
	operation_id: identifier,
	path: livePathSchema,
	expires_in_ms: z.number().int().min(0).max(LIVE_FILE_WAIT_MILLISECONDS),
};

/**
 * One file request the poll hands to the owner. Not strict: a newer server may add a field an older owner ignores.
 * `expires_in_ms` is relative to the moment the owner received the answer; the owner measures it with its own clock and
 * answers `expired`, without touching the disk, if it cannot start the operation in that time.
 */
export const ownerFileRequestSchema = z.discriminatedUnion("kind", [
	z.object({ ...requestBase, kind: z.literal("list"), max_entries: z.number().int().min(1).max(LIVE_FILE_LISTING_MAX_ENTRIES) }),
	z.object({ ...requestBase, kind: z.literal("stat"), hash: z.boolean().default(false) }),
	z.object({
		...requestBase,
		kind: z.literal("read"),
		offset: z.number().int().min(0),
		length: z.number().int().min(1).max(LIVE_FILE_CONTENT_MAX_BYTES),
		mask: z.boolean(),
	}),
	z.object({ ...requestBase, kind: z.literal("write"), content: liveFileTextSchema, precondition: liveFileWritePreconditionSchema }),
	z.object({ ...requestBase, kind: z.literal("delete"), recursive: z.boolean(), precondition: liveFileRemovePreconditionSchema }),
	z.object({ ...requestBase, kind: z.literal("move"), to: livePathSchema, precondition: liveFileRemovePreconditionSchema }),
	z.object({ ...requestBase, kind: z.literal("mkdir") }),
]);

/** Why an owner could not carry out a request. */
export const LIVE_FILE_OWNER_ERROR_CODES = [
	"not_found",
	"not_a_file",
	"not_a_directory",
	"outside_workspace",
	"permission_denied",
	"file_too_large",
	"already_exists",
	"precondition_failed",
	"parent_missing",
	"not_text",
	"path_refused",
	"expired",
	"owner_stopping",
	"owner_busy",
	"helper_failed",
	"helper_timeout",
	"io_error",
	"directory_not_empty",
	"invalid_move",
	"too_many_entries",
] as const;
export const liveFileOwnerErrorCodeSchema = z.enum(LIVE_FILE_OWNER_ERROR_CODES);

const listResult = z
	.object({
		kind: z.literal("list"),
		resolved_path: livePathSchema,
		entries: z.array(liveFileEntrySchema).max(LIVE_FILE_LISTING_MAX_ENTRIES),
		truncated: z.boolean(),
	})
	.strict();

const statResult = z.object({ kind: z.literal("stat"), entry: liveFileEntrySchema }).strict();

const readResult = z
	.object({
		kind: z.literal("read"),
		resolved_path: livePathSchema,
		size: z.number().int().nonnegative(),
		sha256: sha256Hex,
		mode,
		modified_at: timestamp,
		encoding: z.enum(["utf8", "base64"]),
		binary: z.boolean(),
		offset: z.number().int().nonnegative(),
		length: z.number().int().min(0).max(LIVE_FILE_CONTENT_MAX_BYTES),
		content: z.string(),
		truncated: z.boolean(),
		masked: z.boolean(),
	})
	.strict()
	.refine((result) => !result.masked || (result.content === "" && result.length === 0), { message: "a masked read carries no content" });

const writeResult = z
	.object({
		kind: z.literal("write"),
		resolved_path: livePathSchema,
		created: z.boolean(),
		size: z.number().int().nonnegative(),
		sha256_before: sha256Hex.nullable(),
		sha256_after: sha256Hex,
		modified_at: timestamp,
		kept_as: livePathSchema.optional(),
	})
	.strict();

const deleteResult = z
	.object({
		kind: z.literal("delete"),
		resolved_path: livePathSchema,
		directory: z.boolean(),
		removed: z.number().int().nonnegative().max(LIVE_FILE_TREE_MAX_ENTRIES),
		sha256_before: sha256Hex.nullable(),
		tree_sha256_before: sha256Hex.nullable(),
		kept_as: livePathSchema.optional(),
	})
	.strict();

const moveResult = z
	.object({
		kind: z.literal("move"),
		from: livePathSchema,
		to: livePathSchema,
		directory: z.boolean(),
		sha256: sha256Hex.nullable(),
		tree_sha256: sha256Hex.nullable(),
	})
	.strict();

const mkdirResult = z.object({ kind: z.literal("mkdir"), resolved_path: livePathSchema, created: z.boolean() }).strict();

/** The owner's answer to one request: the result, or the code of the error that stopped it. */
export const liveFileOutcomeSchema = z.discriminatedUnion("status", [
	z.object({ status: z.literal("ok"), result: z.discriminatedUnion("kind", [listResult, statResult, readResult, writeResult, deleteResult, moveResult, mkdirResult]) }).strict(),
	z
		.object({
			status: z.literal("error"),
			code: liveFileOwnerErrorCodeSchema,
			message: z.string().max(500),
			current_sha256: sha256Hex.nullable().optional(),
		})
		.strict(),
]);

/** POST /orgs/{tenant}/host/owner/file-results: the supervisor posts the answer to one request. */
export const ownerFileResultRequestSchema = z
	.object({ owner_id: identifier, generation, operation_id: identifier, outcome: liveFileOutcomeSchema })
	.strict();

/** The answer: the result is recorded (also when it repeats one already recorded, byte for byte). */
export const ownerFileResultResponseSchema = z.object({ recorded: z.literal(true) });

/** Why a member-facing file response came from the snapshot although a live computer exists. */
export const liveFileFallbackReasonSchema = z.enum([
	"owner_timeout",
	"owner_error",
	"owner_not_ready",
	"owner_too_old",
	"owner_warming",
	"owner_stopping",
]);

/** The fields every member-facing list, stat and content response carries. */
export const liveFileProvenanceShape = {
	source: z.enum(["live", "snapshot"]),
	as_of: timestamp.nullable(),
	stale: z.boolean(),
	fallback_reason: liveFileFallbackReasonSchema.nullable(),
	retry_after_ms: z.number().int().min(LIVE_FILE_RETRY_AFTER_MIN_MILLISECONDS).max(LIVE_FILE_RETRY_AFTER_MAX_MILLISECONDS).optional(),
};

export const liveFileListingResponseSchema = z.object({
	...liveFileProvenanceShape,
	path: livePathSchema,
	truncated: z.boolean(),
	entries: z.array(liveFileEntrySchema).max(LIVE_FILE_LISTING_MAX_ENTRIES),
});

export const liveFileStatResponseSchema = z.object({ ...liveFileProvenanceShape, entry: liveFileEntrySchema });

export const liveFileContentResponseSchema = z.object({
	...liveFileProvenanceShape,
	path: livePathSchema,
	size: z.number().int().nonnegative(),
	sha256: sha256Hex,
	encoding: z.enum(["utf8", "base64"]),
	binary: z.boolean(),
	offset: z.number().int().nonnegative(),
	length: z.number().int().nonnegative(),
	content: z.string(),
	truncated: z.boolean(),
	masked: z.boolean(),
	revealed: z.boolean(),
	editable: z.boolean(),
	modified_at: timestamp.nullable(),
	overlay: z.enum(["none", "pending", "conflict"]),
	mine_sha256: sha256Hex.nullable().optional(),
});

/** PUT /orgs/{tenant}/computer/files/content?path=  with If-Match: "<sha256>" or If-None-Match: *  */
export const liveFileWriteBodySchema = z.object({ content: liveFileTextSchema }).strict();

export const liveFileWriteResponseSchema = z.object({
	source: z.enum(["live", "overlay"]),
	as_of: timestamp,
	path: livePathSchema,
	created: z.boolean(),
	size: z.number().int().nonnegative(),
	sha256: sha256Hex,
	previous_sha256: sha256Hex.nullable(),
	modified_at: timestamp,
	kept_as: livePathSchema.nullable(),
	/** false for a live edit (on the computer's disk, not yet in the saved copy); true for an overlay edit (already part of the saved copy as the next read sees it). */
	backed_up: z.boolean(),
});

/** POST /orgs/{tenant}/computer/files/reveal */
export const liveFileRevealBodySchema = z
	.object({
		path: livePathSchema,
		offset: z.number().int().min(0).optional(),
		length: z.number().int().min(1).max(LIVE_FILE_CONTENT_MAX_BYTES).optional(),
	})
	.strict();

/** POST /orgs/{tenant}/computer/files/overlay/discard: drop one pending overlay change of any kind (the revision is the entry's). */
export const liveFileDiscardBodySchema = z.object({ path: livePathSchema, revision: z.number().int().positive() }).strict();

/** POST /orgs/{tenant}/computer/files/move: rename a file, a symlink or a directory; header If-Match of the effective hash of `from` (L49). */
export const liveFileMoveBodySchema = z.object({ from: livePathSchema, to: livePathSchema }).strict();

/** POST /orgs/{tenant}/computer/files/directories: create a directory; idempotent. */
export const liveFileMkdirBodySchema = z.object({ path: livePathSchema }).strict();

/** DELETE /orgs/{tenant}/computer/files?path=&recursive=  with If-Match of the effective hash (L49). */
export const liveFileDeleteResponseSchema = z.object({
	source: z.enum(["live", "overlay"]),
	as_of: timestamp,
	path: livePathSchema,
	directory: z.boolean(),
	removed: z.number().int().nonnegative(),
	kept_as: livePathSchema.nullable(),
	backed_up: z.boolean(),
});

export const liveFileMoveResponseSchema = z.object({
	source: z.enum(["live", "overlay"]),
	as_of: timestamp,
	from: livePathSchema,
	to: livePathSchema,
	directory: z.boolean(),
	sha256: sha256Hex.nullable(),
	tree_sha256: sha256Hex.nullable(),
	backed_up: z.boolean(),
});

export const liveFileMkdirResponseSchema = z.object({
	source: z.enum(["live", "overlay"]),
	as_of: timestamp,
	path: livePathSchema,
	created: z.boolean(),
	backed_up: z.boolean(),
});

/** POST /orgs/{tenant}/computer/files/watch: the Files panel is open (true) or closed (false). */
export const liveFileWatchBodySchema = z.object({ open: z.boolean() }).strict();

export const liveFileWatchResponseSchema = z.object({
	state: z.enum(["off", "starting", "live"]),
	interactive_until: timestamp.nullable(),
	poll_interval_ms: z.number().int().min(250).max(60000).nullable(),
});

/** The body of every member-facing file refusal (Phase 1 shape, extended). */
export const liveFileErrorSchema = z.object({
	error: z.string(),
	message: z.string(),
	current_sha256: sha256Hex.nullable().optional(),
	retry_after_ms: z.number().int().positive().optional(),
	kept_as: livePathSchema.optional(),
});

export type OwnerFileRequest = z.infer<typeof ownerFileRequestSchema>;
export type LiveFileOutcome = z.infer<typeof liveFileOutcomeSchema>;
export type OwnerFileResultRequest = z.infer<typeof ownerFileResultRequestSchema>;
export type LiveFileEntry = z.infer<typeof liveFileEntrySchema>;
export type LiveFileOwnerErrorCode = z.infer<typeof liveFileOwnerErrorCodeSchema>;
export type LiveFileFallbackReason = z.infer<typeof liveFileFallbackReasonSchema>;
export type LiveFileWriteResponse = z.infer<typeof liveFileWriteResponseSchema>;

A schema test (conversation/test/live-files-protocol-schema.test.ts) must prove at least: the largest read result (a 262144 byte range of binary, base64) serialized as a table item is under 380,000 bytes (L20); a write of 262144 bytes of multi-byte text passes and one byte more fails; a path with .., a NUL, a relative path and a path outside /workspace fails; a masked read result with content fails; a request with an unknown field fails and a poll response with an unknown field passes.

5.3 Edits to host-protocol/src/supervisor.ts

/** The first protocol version whose owner understands file_requests in the poll response. */
export const OWNER_FILE_REQUESTS_PROTOCOL_VERSION = 2;

/** Milliseconds between polls while a Files panel is open, in the states that can serve a file request. */
export const OWNER_POLL_INTERACTIVE_MILLISECONDS = 1000;

// ownerErrorCodeSchema gains "operation_closed" and "overlay_not_sealed"; OWNER_ERROR_STATUS maps both to 409.
// ownerStopVetoReasonSchema gains "file_operation_pending".
// ownerPollResponseSchema gains, beside dispatches:
//   file_requests: z.array(ownerFileRequestSchema).max(LIVE_FILE_MAX_REQUESTS_PER_POLL).default([]),
// The two refinements (drain_reason, no dispatch while draining) are unchanged; file_requests are allowed while draining.

OWNER_PROTOCOL_VERSION stays 1 in F0. Part C changes it to 2 in the same pull request that makes the supervisor handle file_requests (L3). ownerPollRequestSchema is unchanged.

5.4 Owner error codes

overlay_not_sealed (409): the overlay is not sealed by this owner and generation (it was never sealed, or a newer owner replaced the seal). operation_closed (409): the request was abandoned, expired, answered already with a different result, never delivered to this owner, or belongs to another computer. The supervisor drops the operation on it. The existing rules for 401, 403 and 409 stale_poll of OWNER_SUPERVISOR_PROTOCOL 9.5 apply to the new route unchanged: a 401 or a superseding 403 ends the supervisor.

5.5 host-protocol/src/edit-overlay.ts (revision 2)

import { z } from "zod";
import { livePathSchema } from "./live-files.ts";

export const OVERLAY_INDEX_VERSION = 1;
export const OVERLAY_MAX_ENTRIES = 100;
export const OVERLAY_MAX_TOTAL_BYTES = 8388608;
export const OVERLAY_INDEX_MAX_BYTES = 262144;
export const OVERLAY_CAS_ATTEMPTS = 3;
export const OVERLAY_APPLY_BUDGET_SECONDS = 30;
export const OVERLAY_SEAL_RETRY_AFTER_MILLISECONDS = 2000;
export const OVERLAY_STOPPING_RETRY_AFTER_MILLISECONDS = 5000;
export const OVERLAY_CLEAR_RETRY_SECONDS = 10;
export const OVERLAY_EARLY_PUBLISH_SECONDS = 5;
export const OVERLAY_INDEX_OBJECT = "overlay/index.json";
export const overlayBlobObject = (sha256: string): string => `overlay/blobs/${sha256}`;

const identifier = z.string().min(1).max(256);
const timestamp = z.iso.datetime();
const sha256Hex = z.string().regex(/^[0-9a-f]{64}$/);

/** A conflict: the disk held something else than the change expected. Derived conflicts (the snapshot moved) are not stored. */
export const overlayConflictSchema = z
	.object({
		reason: z.enum(["changed", "collision", "not_empty", "kind_mismatch"]),
		disk_sha256: sha256Hex.nullable(),
		found_at: timestamp,
	})
	.strict();

const entryBase = {
	path: livePathSchema,
	edited_by: identifier,
	edited_at: timestamp,
	revision: z.number().int().positive(),
	conflict: overlayConflictSchema.nullable(),
};
const mode = z.string().regex(/^[0-7]{3,4}$/);

/** One pending change. One path has at most one entry. The content of a `put` is the blob named by `sha256`; the other kinds carry no blob. */
export const overlayEntrySchema = z.discriminatedUnion("op", [
	z
		.object({
			...entryBase,
			op: z.literal("put"),
			sha256: sha256Hex,
			size: z.number().int().nonnegative().max(262144),
			mode,
			base_sha256: sha256Hex.nullable(),
			/** The file this put was renamed from (hidden, and deleted at apply with `from_sha256`); null for a plain create or replace. */
			from: livePathSchema.nullable(),
			from_sha256: sha256Hex.nullable(),
		})
		.strict(),
	z
		.object({
			...entryBase,
			op: z.literal("delete"),
			directory: z.boolean(),
			recursive: z.boolean(),
			/** The effective hash seen: a file's content hash or a symlink's hash (L49); null for a directory. */
			base_sha256: sha256Hex.nullable(),
			/** The tree hash seen, for a directory. */
			tree_sha256: sha256Hex.nullable(),
		})
		.strict(),
	z.object({ ...entryBase, op: z.literal("mkdir"), mode }).strict(),
	z
		.object({
			...entryBase,
			op: z.literal("move"),
			from: livePathSchema,
			directory: z.boolean(),
			/** The kept content hash of a moved file or symlink; null for a directory. */
			sha256: sha256Hex.nullable(),
			/** The tree hash of a moved directory. */
			tree_sha256: sha256Hex.nullable(),
			size: z.number().int().nonnegative(),
			mode,
		})
		.strict(),
]);

/** Who may write the index: nobody but the Front Door; and not at all while a valid seal exists. */
export const overlaySealSchema = z
	.object({ owner_id: identifier, generation: z.number().int().positive(), sealed_at: timestamp, snapshot_generation: z.number().int().nonnegative() })
	.strict();

/** The object `overlay/index.json`. Paths are unique; the contents add up to at most 8 MiB. */
export const overlayIndexSchema = z
	.object({
		version: z.literal(OVERLAY_INDEX_VERSION),
		sealed: overlaySealSchema.nullable(),
		entries: z.array(overlayEntrySchema).max(OVERLAY_MAX_ENTRIES),
	})
	.strict()
	.refine((index) => new Set(index.entries.map((entry) => entry.path)).size === index.entries.length, { message: "paths are unique" })
	.refine(
		(index) => {
			const sources = index.entries.flatMap((entry) => (("from" in entry && entry.from !== null) ? [entry.from] : []));
			return new Set(sources).size === sources.length && sources.every((source) => !index.entries.some((entry) => entry.path === source));
		},
		{ message: "a source path is moved once and is not also an entry" },
	)
	.refine(
		(index) => index.entries.reduce((total, entry) => total + (entry.op === "put" ? entry.size : 0), 0) <= OVERLAY_MAX_TOTAL_BYTES,
		{ message: "content over 8 MiB" },
	);

/** POST /orgs/{tenant}/host/owner/overlay-seal: after extraction, close the overlay to member writes and get the entries to apply. */
export const ownerOverlaySealRequestSchema = z.object({ owner_id: identifier, generation: z.number().int().positive() }).strict();
export const ownerOverlaySealResponseSchema = z.object({ entries: z.array(overlayEntrySchema).max(OVERLAY_MAX_ENTRIES) });

const entryReference = z.object({ path: livePathSchema, revision: z.number().int().positive() }).strict();

/**
 * POST /orgs/{tenant}/host/owner/overlay-applied: after a publish that began after the apply, clear exactly these entries;
 * and/or report entries that were not applied because the disk held a third version.
 */
export const ownerOverlayAppliedRequestSchema = z
	.object({
		owner_id: identifier,
		generation: z.number().int().positive(),
		cleared: z.array(entryReference).max(OVERLAY_MAX_ENTRIES).default([]),
		conflicts: z.array(entryReference.extend({ reason: overlayConflictSchema.shape.reason, disk_sha256: sha256Hex.nullable() })).max(OVERLAY_MAX_ENTRIES).default([]),
	})
	.strict();
export const ownerOverlayAppliedResponseSchema = z.object({ remaining: z.number().int().nonnegative() });

export type OverlayIndex = z.infer<typeof overlayIndexSchema>;
export type OverlayEntry = z.infer<typeof overlayEntrySchema>;

A schema test proves: a 101st entry fails, duplicate paths fail, a source path moved twice or also an entry fails, 8 MiB of put content plus one byte fails (deletes, moves and mkdirs add none), an entry with a path outside /workspace fails, each of the four kinds parses, cleared and conflicts default to empty, and an index with a seal parses.

6. Routes

6.1 Owner routes (audience computer-owner)

The three new routes (file-results, overlay-seal, overlay-applied) are added to OWNER_COMPUTER_ROUTES. Authentication is section 5.1 of OWNER_SUPERVISOR_PROTOCOL, unchanged: signature, audience, tenant, computer, generation, live owner. Additionally the handler requires that the request item names this owner id, this computer and this generation (409 operation_closed otherwise).

6.2 Member routes (audience user)

All under /orgs/{tenant_id}/computer/files, resolved by resolveUserPrincipal (http/user-principal.ts) exactly as the Phase 1 routes are. Every response carries X-Content-Type-Options: nosniff and Cache-Control: private, no-store; content responses add Vary: Authorization. A refusal of the principal is the Phase 1 { "detail": ... } 403.

Header rules for PUT: exactly one of the two preconditions (both or neither: 428 precondition_required); If-Match takes one strong quoted 64 hex digit value ("abc..."; *, a list, a weak W/ value or a malformed value: 400 invalid_body); If-None-Match takes * only. CloudFront forwards both headers on /api* (OriginRequestPolicy.ALL_VIEWER_EXCEPT_HOST_HEADER, allowedMethods: ALLOW_ALL, infra/lib/web-stack.ts:139-152) and the web app and the API share an origin, so there is no CORS to configure. ASSUMPTION: CloudFront does not strip If-Match or alter ETag; Part A2 checks it on development.

6.3 Member error codes and statuses

The body is { "error": code, "message": text } plus current_sha256, retry_after_ms or kept_as where the code says so. LIVE_FILE_ERROR_STATUS is this table.

Owner error to member response, for the cases not in the table above: outside_workspace and permission_denied become 403 path_refused (with the owner's message), owner_stopping on a write becomes 503 computer_stopping, owner_busy becomes 429 too_busy, expired becomes 504 owner_timeout, helper_timeout on a write becomes 504 outcome_unknown (the rename may have happened), on a read it falls back. For reads, the channel failures of L28 fall back to the snapshot with fallback_reason owner_timeout (no result in time or helper_timeout, expired), owner_error (helper_failed, io_error, owner_busy) or owner_stopping.

7. Server behavior

7.1 Records

Computer record (store/codecs/computer.ts) gains two optional fields. Both are removed with the other owner fields (OWNER_ATTRIBUTE_NAMES, withoutOwner) when an owner ends or a generation is claimed, and both must be encoded and decoded or a putComputer drops them.

Request item (new codec store/codecs/live-file-operation.ts): partition {tenant}#computer#fileops, sort key op#{operation_id}; operation_id is fop- plus an id from deps.ids.

The per-turn role has no access to either partition (owner-role-policy.json MessagingWritable lists exactly computer#actions and computer#record); the supervisor role has no DynamoDB access at all.

Audit item (new codec store/codecs/file-audit.ts): partition {tenant}#computer#audit, sort key at#{epoch milliseconds, 13 digits}#{operation_id}.

No file content, no body, no token is ever stored. A reader treats a record past expires_at as absent and a pending record older than 120 seconds as unknown.

Stored answer. The outcome attribute of the request item is the JSON of the owner's answer deflated (a DynamoDB binary attribute), not text. A listing of 2000 entries is about 540 KB as text, past the 400 KB an item holds (W14 counted only the 256 KiB read), and about a tenth of that deflated; codecs/live-file-operation.ts encodeOutcome and its decode are the one place that knows.

Worker item (store/codecs/worker.ts): gains pollPaceMilliseconds (poll_pace_ms), the pace the control plane last told the owner (part A1). Expected pickup (L27) is lastHeartbeatAt + pollPaceMilliseconds - now, and the watch answer reports the pace from it. It is cleared with the other poll fields when the owner exchanges its bootstrap token.

Rate counters: partition U#{user_id} (the user partition of dynamo-messaging-store.ts), sort key file_rate#{class}#{bucket}, attributes attempt_count, expires_at; the new store method incrementRateCounter(userId, name, now, windowSeconds) returns the count, and incrementOrganizationCreationAttempts is re-expressed through it (one implementation).

7.2 Reading: choosing live or snapshot

liveFileSourceOf(computer, worker, now) -> "live" | { snapshot, reason }
  computer is null or has no owner               -> snapshot, no reason, stale=false     (the computer is off)
  not liveOwnerOf(computer, worker, now, 30)     -> snapshot, no reason, stale=false     (heartbeat lapsed: treated as off)
  computer.ownerProtocolVersion < 2              -> snapshot, owner_too_old,  stale=true
  worker.pollState in {booting, hydrating}       -> snapshot, owner_not_ready, stale=true
  worker.pollState is stopping, or computer.ownerStopApprovedAt set  -> snapshot, owner_stopping, stale=true
  computer.hydrateRequired                       -> snapshot, owner_not_ready, stale=true
  else                                           -> live

Steps of a GET (list, stat, content), first failure wins:

1. resolveUserPrincipal (member of the path organization, organization enabled): else the Phase 1 refusal. 429 rate_limited from the read counter. livePathProblem (400).
2. getComputer, getWorker(computer.ownerId), liveFileSourceOf.
3. Snapshot: the Phase 1 service with the provenance fields added and the overlay merged over it (7.7.2). A computer with no snapshot answers an empty /workspace plus the overlay; no_snapshot (404) only when there is neither. A live-eligible computer never reaches here.
4. Live:
   1. expected pickup (L27). More than 7 seconds: set the interactive window (a conditional update of the record, owner still live), answer from the snapshot with owner_warming and retry_after_ms.
   2. Fewer than 16 open requests (a Query ... Select COUNT of the partition): else 429 too_busy.
   3. Queue the request in one transaction: Update the computer record (SET interactive_until_at = :t, file_operation_id = :op, condition owner_id = :owner AND owner_generation = :g AND attribute_not_exists(owner_stop_approved_at)) and Put the request item (attribute_not_exists(pk), status pending, expires_at). A canceled transaction is treated as "the owner stopped": snapshot, owner_stopping.
   4. Wait: loop, strongly consistent GetItem of the request item every 250 ms, until done or 8 seconds on the injected clock.
   5. done: delete the item, map the outcome (6.3). A secret-looking resolved_path on a read that was not a reveal and not masked (an owner that did not mask) is masked here: content dropped, masked: true (L25).
   6. Timeout (8 seconds after queueing): one conditional update pending -> abandoned that removes request and outcome. Won: fall back to the snapshot with owner_timeout. Lost because the status is delivered: the owner has the request. A read does not wait longer: it sets waiter_gone on the item (conditional on delivered) and falls back to the snapshot. Lost because the status is done: read the outcome as in step 5.
5. stale is true for any snapshot answer whose fallback_reason is not null. A live answer has source: "live", stale: false, as_of = the Front Door's clock at the answer.

editable (content only): source === "live" and !masked (or revealed) and !binary and !truncated and size <= 262144.

7.3 Writing: PUT .../files/content

One request, two paths: the owner when it can serve, the overlay otherwise. First failure wins.

1. Principal: kind === "user" or "integration", userId !== null, enabled organization (L24). 403 otherwise.
2. Write rate counter (429). Parse the precondition headers (428, 400). Parse the body with liveFileWriteBodySchema (400 invalid_body; a body over 256 KiB is 413 content_too_large, checked from Content-Length first and again after parsing).
3. livePathProblem (400). The normalised path has a .git segment: write the audit record with outcome refused, error_code path_refused, answer 403. (A refusal is audited, L29.)
4. Route. Read the computer record and the owner's worker item. First match wins:
   1. The organization is a customer-account organization: 409 edit_unsupported (L46).
   2. liveFileSourceOf is live (L2): the live path, steps 5 to 12 below.
   3. A live owner (liveOwnerOf) with protocol version below 2: 409 owner_too_old (L47).
   4. A live owner that is stopping or has ownerStopApprovedAt, and the overlay is sealed by it: 503 computer_stopping.
   5. A live owner that is booting or hydrating: read the overlay index; sealed by it: 503 computer_starting; not yet sealed: the overlay path (7.7.3).
   6. No live owner (off, lapsed heartbeat, hydrateRequired, any stale seal): the overlay path (7.7.3). None of these refusals is audited (nothing was attempted).

The live path:

5. Fewer than 16 open requests (429 too_busy).
6. expected pickup (L27): too slow: set the interactive window and answer 503 owner_warming with retry_after_ms; nothing is queued and nothing is audited. The UI keeps the person's text and asks again at that time.
7. Write the audit record, outcome: "pending" (L21). If the write fails: 503 audit_unavailable, nothing queued.
8. markComputerDiskDirty (L14).
9. Queue the request (transaction of 7.2 step 4.3). Canceled (the owner stopped in between): finalize the audit record failed/owner_stopping, answer 503 computer_stopping.
10. Wait (7.2 step 4.4). On done delete the item and map the outcome:
    • ok write: 200, liveFileWriteResponseSchema with source: "live", ETag: "<sha256_after>", backed_up: false.
    • error precondition_failed or already_exists: 409 with current_sha256.
    • the other owner errors per 6.3.
11. Timeout: pending -> abandoned conditional update. Won: 504 owner_timeout, nothing happened, the audit record is finalized failed. Lost because the status is delivered: wait up to 7 more seconds (LIVE_FILE_OUTCOME_GRACE_MILLISECONDS); still nothing: set waiter_gone on the item (conditional on delivered) and answer 504 outcome_unknown. The audit record stays pending and becomes ok or failed whenever the result route hears the owner.

The result route (7.4) finalizes the audit record of a live write. The waiting handler never writes the outcome, so a late result is still recorded. A create (If-None-Match: *) is audited as create; a replace as write.

7.4 The result route and the poll

POST /host/owner/file-results handler, after authentication (6.1):

1. Parse (422). owner_id and generation equal the principal's (403 credential_mismatch).
2. Read the item (consistent). Absent, past expires_at, other owner, other computer, other generation, status abandoned or pending: 409 operation_closed. Status done: if the stored outcome equals this one, 200 (idempotent); else 409.
3. The result's kind must equal the request's kind (422 invalid_request).
4. One conditional update delivered -> done setting outcome. Lost: re-read and treat as step 2. If the item has waiter_gone, the handler deletes the item after step 5 and does not keep the outcome (the content of a read nobody is waiting for is not stored).
5. Finalize the audit record (conditional on it existing): outcome from the result (ok, conflict for precondition_failed and already_exists, refused for path_refused, failed otherwise), resolved_path, kept_as, the reported hashes, and the integrity_mismatch flag when sha256_after reported differs from computed. A failure here: 503 (the supervisor retries; the update in step 4 is idempotent). For operations that carry no audit record (reads) there is no step 5.
6. 200 { "recorded": true }.

In pollOwner, after "settle lost actions" and before "drain" (the order of 5.3 of the supervisor contract; drain is computed after), when request.protocol_version >= 2, the request state is idle, serving, publishing or draining, computer.ownerStopApprovedAt is unset and computer.interactiveUntilAt > now:

1. Query the partition for items with status = pending for this owner and generation, oldest first, limit 4, ignoring items past expires_at; plus the items with status = delivered and delivered_sequence = request.sequence (a repeated poll).
2. For each pending one, conditional update pending -> delivered, delivered_at, delivered_sequence = request.sequence, owner id. A lost update skips it.
3. Return them in file_requests with expires_in_ms = max(0, 8000 - (now - queued_at)). A request already past 8 seconds is not delivered (it is being abandoned).

Cadence: next_poll_ms = ownerPollCadence(state, idleSeconds); if interactiveUntilAt > now and the state can serve files, min(that, OWNER_POLL_INTERACTIVE_MILLISECONDS) (L7). ownerPollCadence keeps its signature; the interactive clamp is a second function ownerFilePanelPace.

Stop request. stopVeto for reason: "idle" gains, after the parked work check: any non-expired item with status pending or delivered for this computer: veto file_operation_pending. approveOwnerStop gains a second guard, attribute_not_exists(file_operation_id) OR file_operation_id = :seen, where :seen is the value read when the predicate was judged; the existing three-attempt re-judge loop covers a lost race (L11).

7.5 Reveal and watch

Reveal (POST /reveal): steps 1, 2 (reveal counter), 3 of a GET, then the audit record (operation: "reveal", revealed: true, secret_name as the predicate says; fail closed with 503), then the same live-or-snapshot choice. Live: a read request with mask: false. Snapshot: the Phase 1 service with a reveal option that skips the masking. The response is a content response with masked: false, revealed: true. The audit record is finalized ok by the Front Door for the snapshot source and by the result route for the live source. A reveal of a path that does not look secret is still a read and still audited.

Watch (POST /watch): principal, watch counter. open: true: if there is a live owner able to serve files (liveFileSourceOf is live), conditionally update the record (owner_id, generation, not stop-approved) SET interactive_until_at = now + 45 s and answer state: "live" with poll_interval_ms = the pace the owner was last given (ownerFilePanelPace). state: "starting" when an owner exists in booting or hydrating or the computer has an unexpired start lease; state: "off" otherwise. open: false: if live, SET interactive_until_at = now; answer as above. The ping does not queue a request, does not touch the idle state and is not audited (so a forgotten panel does not keep the computer awake, L12, O2).

7.6 Retention and cleanup

Readers ignore any item past expires_at. Part A1's contract test inserts an expired item and proves the poll, the result route and the count do not see it.

7.7 The edit overlay (revision 2)

7.7.1 Objects

In the computer's snapshot prefix, tenants/{T}/computers/{K}/:

The supervisor reads them (its role already allows GetObject on the prefix) and is denied every write (12.8). Nothing in the overlay names a path in an S3 key: blobs are addressed by hash, so no member-chosen string becomes a key.

7.7.2 The effective view

This subsection describes put entries; the effective view with delete, mkdir and move entries is 7.8.3, and the effective hash of a symlink or a directory is 7.8.2.

Inputs: the snapshot index (an empty one holding only the directory /workspace when nothing was published) and the overlay index (a conditional GET with the cached ETag; an absent object is an empty overlay). For each path with an entry E, and s the snapshot hash of the path (absent is a value):

• List: the snapshot's children of the directory, plus the pending and applied-looking entries whose parent is the directory and which the snapshot lacks (new files); same order and the same 2000 cap.
• Stat, content, reveal: a pending entry is served from its blob; the bytes are hashed and must equal E.sha256 (else 500 corrupt_snapshot, logged). variant=mine serves the blob of an entry in conflict. Masking and binary sniffing are the snapshot's.
• Effective hash (L32) is the shown sha256: the entry's when pending, otherwise the snapshot's. This is the ETag.
• A write whose content hash equals the effective hash is a no-op: 200, nothing written, no audit record.

7.7.3 Writing, discarding

Reached from 7.3 step 4.5 or 4.6. Steps, first failure wins:

1. Path rules (L40) against the snapshot index: a segment in PACK_EXCLUDED_DIRECTORY_NAMES is 422 not_in_saved_copy; the path or an ancestor is a symlink in the index, 403 path_refused; the path is a directory, 422 not_a_file; the parent directory is not in the index (and is not /workspace), 404 parent_missing.
2. GET overlay/index.json (ETag E, or absent), parsed with overlayIndexSchema. A valid seal (L33) was already handled by 7.3 step 4; a seal that is present but stale is carried into step 7 and cleared by the swap.
3. Judge the precondition against the effective hash (7.7.2). If-Match differs: 409 precondition_failed with current_sha256 (the snapshot's for a conflicted path). If-None-Match: * and the path exists in the effective view: 409 already_exists.
4. Caps (L41): the entry count after the write and the sum of sizes: else 409 overlay_full.
5. Write the audit record (source: "overlay", outcome: "pending"); 503 audit_unavailable if it cannot, nothing written.
6. PUT overlay/blobs/{sha256} with If-None-Match: *; a 412 means it exists and is fine.
7. Build the new index: the entry { path, sha256, size, mode, base_sha256, edited_by, edited_at, revision, conflict: null } where mode is the existing entry's, else the snapshot entry's, else "664"; base_sha256 is the existing entry's, else the snapshot hash of the path (null for a create), and the snapshot hash when the existing entry was in conflict (the person overwrote on purpose); revision is the old one plus 1, else 1; sealed: null. PUT overlay/index.json with If-Match: E (If-None-Match: * when absent).
8. A failed swap (412): re-read and go back to step 3, at most OVERLAY_CAS_ATTEMPTS (3) times; a changed effective hash is the 409 of step 3.
9. Finalize the audit record ok; delete the replaced blob if no entry names it (best effort); answer 200, liveFileWriteResponseSchema with source: "overlay", backed_up: true, ETag: "<sha256>".

Discard (POST .../overlay/discard): principal, write counter, path, 7.3 step 4 (so a sealed overlay is 503), read the index; the entry must exist with this sha256 (409 precondition_failed otherwise); audit record (operation: "discard"); swap the entry out (same loop); delete its blob. Any enabled member may discard (the workplace is shared and every discard is audited).

7.7.4 The owner: seal, apply, clear

In the supervisor's hydrate() (section 9.4), in this order and before the supervisor leaves hydrating:

1. Extract the snapshot and share the workspace with the shell user (existing). Also when the local cache matched, and also when there is no snapshot (L42).
2. POST overlay-seal. The Front Door authenticates the owner (section 5.1 of the supervisor contract), reads the index, and writes it with sealed = { owner_id, generation, sealed_at, snapshot_generation } (the computer record's snapshotGeneration at that moment) by compare-and-swap (creating it with If-None-Match: * if absent). A seal already held by this owner and generation is returned as is (a retry). A seal of anyone else is stale by construction (this owner is the live owner) and is replaced. A lost swap re-reads: a member edit that won the swap is in the set. The response carries every entry.
3. Apply every entry without a stored conflict in the order and with the rules of 7.8.5 (mkdir, directory moves, file moves, puts, deletes of files, deletes of directories). For a put: read its blob from S3, check the bytes hash to entry.sha256, and call the file helper write with if_match base_sha256 (if_none_match when base_sha256 is null) and refuseGitSegments. ok: applied. precondition_failed whose current_sha256 equals entry.sha256: already applied. Any other outcome of precondition_failed or already_exists: conflict. The other operations use the helper operations of 8.1 and the outcomes of 7.8.5. A blob that cannot be read or does not hash, or a helper failure other than those, fails the hydrate (L34).
4. If there are conflicts, POST overlay-applied { conflicts }, each with the reason the owner found (changed, collision, not_empty or kind_mismatch, the column of 7.8.5) and the disk_sha256 it saw. The Front Door stores conflict: { reason, disk_sha256, found_at } on each entry whose revision still matches, and writes an overlay_apply audit record with outcome conflict. Failing this post is logged and retried; it does not fail the hydrate.
5. Remember the applied set. If the disk now equals the published index (nothing to publish) go to 7 at once.
6. Return from hydrate(); the supervisor is idle. The first publish check is 5 seconds later (L36). A turn that arrives first runs; the entries stay.
7. When a publish starts, capture the applied set; after publishComputerSnapshot succeeds, POST overlay-applied { cleared } for that set. The Front Door removes each entry whose path, revision and sha256 match and for which a publish is on record (the rule of L37; an entry without one simply stays, and remaining says so), deletes blobs no entry names, writes overlay_apply records (outcome ok), and answers remaining. Entries not named stay. A failed post is retried every 10 seconds and before the stopped report.

The seal ends with the owner: the stopped report unseals (one swap). A seal left by a dead owner is stale (L38).

7.7.5 Transitions

7.7.6 The races, exactly

• R1, an edit against the seal. Both are compare-and-swaps of overlay/index.json. The one that swaps first wins. An edit that loses re-reads, sees the seal and answers 503 computer_starting (an unreferenced blob remains); an edit that won is in the set the seal returns. There is no third outcome.
• R2, an edit while the snapshot is being extracted. The seal is written after extraction, so the edit is in the sealed set and is applied before any turn.
• R3, two members editing while off. Each judges against the effective hash it read; the second swap fails if the first changed the index; it re-reads and re-judges. The same path with a now-stale If-Match: 409 with the first member's hash. Different paths: both stand.
• R4, the apply against a live edit. No file operation is delivered before the supervisor leaves hydrating (the poll delivers only in idle, serving, publishing, draining). The clear names path, revision and sha256 that were applied, never what the disk holds now.
• R5, a lost clear. Nothing is removed until the control plane records it. An applied entry that stays is idempotent at the next hydrate (the disk equals the entry: already applied). Only if the bot also changed the file in a later successful publish and the clear was lost until the next hydrate does the owner find a third hash and report a conflict; that false conflict needs two failures in a row and is surfaced, not resolved silently. The supervisor retries every 10 seconds and before the stopped report to make it rare.
• R6, a takeover in the middle of the apply. The new owner seals again (the old seal is stale, replacing it is one swap) and applies from the snapshot on its own disk. The old owner's disk is not the new one's.
• R7, a snapshot published by something that does not know the overlay (a customer host, a protocol 1 owner): the entry is a derived conflict at the next read and a stored conflict at the next apply. The person's text is kept and readable; nothing is overwritten.
• R8, a discard against the seal. The same compare-and-swap as R1.
• R9, the audit. The record is written before the blob and the swap, so every accepted edit has a record; one for an edit that then lost a swap is finalized failed.

7.7.7 Size and cost

Caps in L41. Cost in section 19.

7.8 Delete, rename and new folders (revision 3)

7.8.1 Routes, roles, preconditions

Routes are in 6.2. Principal and rate rules are those of a write (7.3 steps 1 to 3, class write); the route decision is 7.3 step 4 (live path or overlay path) for every one of them.

Who may (L51). The original design (7.6, D8) said "Delete and move, when added, need the owner role". That no longer stands for the common case: delete, rename and new folders now matter to every member, who can already change a file and can already tell a bot to delete anything. Recommendation, adopted in the contract: any enabled member may delete a file or a symlink, rename a file, a symlink or a directory, create a directory, and delete an empty directory, each audited with who, what and the hash seen; only the organization owner role may delete a non-empty directory (recursive=true), the one bulk, hard-to-undo action. A member who tries gets 403 owner_role_required, and the refusal is audited as refused (7.8.8 decides; an earlier draft said it was only logged). recursive=true needs the owner role whether or not the folder has children: the flag is the request for the bulk delete, so the rule is one rule on both paths and an empty folder is deleted by a member with recursive absent. Renaming a non-empty directory is not destructive and is open to members.

Preconditions (L49, L50). DELETE and move require If-Match of the effective hash of the path as the person last saw it; the ETag of stat and of content is that hash (a directory's is its tree hash). A missing header is 428; a different hash is 409 precondition_failed with current_sha256 (the tree hash for a directory). POST /directories takes no precondition: it is idempotent.

7.8.2 The effective hash

File: SHA-256 of the content. Symlink: SHA-256 of symlink, a NUL byte, then the target. Directory (the tree hash): SHA-256 over, for every descendant of the directory in the effective view sorted by relative path (bytes), the line kind NUL relative-path NUL value LF, with kind one of file, symlink, dir, and value the size of a file, the target of a symlink, or 0. The tree hash of an empty directory is the hash of nothing. The Front Door computes it from the merged snapshot index and overlay; the helper computes the same from lstat and readlink (no file is read). A directory with more than 5000 descendants is 413 too_many_entries for a delete, a rename and a tree hash.

7.8.3 Reads: how the four operations merge

Added to the rules of 7.7.2. s is the snapshot's state of a path.

• List. The children of a directory are the snapshot's children, minus every path hidden by a delete or by the source of a move or put with from, plus the entries whose parent is the directory (puts, mkdirs, move targets). A hidden directory hides its subtree. Order and the 2000 cap are unchanged.
• Stat, content, reveal. A path under a moved directory is translated to the snapshot path before lookup (the exclusivity of L53 means no other entry is below it). A moved file's content is a ranged read of the snapshot member of its source, verified against the kept hash.
• Pending changes. GET .../files/overlay returns the entries so the panel can mark them and offer a discard.

7.8.4 Recording a change (the write algebra)

Steps 1 to 5 of 7.7.3 apply to every operation (path rules L40 and L59, judge the precondition against the effective hash, caps, audit intent first, fail closed), then the blob step only for a put, then the swap of 7.7.3 steps 7 and 8 with the new set of entries, then the audit finalization. The new set is computed from the entry at the path and the operation:

A request that names a missing parent is 404 parent_missing; a target that exists is 409 already_exists; a source that does not exist is 404 not_found.

7.8.5 Applying at hydrate: order and collisions

The supervisor applies the sealed set (7.7.4 step 3) in this order, each operation through the file helper with its precondition (8.1), as uid 2000, containment and refuseGitSegments included:

1. mkdir, shallowest path first.
2. Directory moves, shallowest source first. Exclusivity (L53) means they do not interact.
3. Moves of files and symlinks.
4. Puts (creates and replaces), in path order. A put with from is a create at its path; its source is removed in step 5.
5. Deletes of files and symlinks, including the sources of puts with from.
6. Deletes of directories, deepest first. A recursive delete is one tree removal.

• Rename onto an existing path: always a conflict (collision), never an overwrite; the request side already refuses it (L52).
• Non-empty directory delete: only the recursive entry removes children; a non-recursive one whose directory gained children meanwhile is a conflict (not_empty).
• Rename of a directory: one rename(2) of the whole tree after mkdir(target); it fails whole if anything about the target changed.
• A conflict is reported with POST overlay-applied { conflicts }, the entry is kept and flagged (conflict.reason), and the operations that depended on it (a put inside a directory whose mkdir conflicted) report collision for the parent that is missing. Nothing is retried in the hydrate.
• Clear (7.7.4 step 7) after a recorded publish, for every applied or already-applied entry, using the rule of L37; for a non-put entry the Front Door additionally accepts the clear when the snapshot index already shows the result (path gone for a delete, directory present for a mkdir, target with the kept hash and source gone for a move).

7.8.6 The live path

When the owner can serve (7.3 step 4.2) the operation is a file request of kind delete, move or mkdir (5.2) with the same preconditions, queued in the same transaction, delivered by the same poll, answered by the same result route, with the same audit (intent first, finalized by the result route), the same markComputerDiskDirty, the same abandon and outcome_unknown rules, and backed_up: false. The Front Door has already checked the owner role for a recursive delete and the path rules; the helper checks containment and .git again. A directory_not_empty, invalid_move, too_many_entries, already_exists or precondition_failed from the helper maps to the member codes of 6.3.

7.8.7 Containment, links, .git

Every path in a request (path, from, to) is validated lexically by the Front Door (livePathProblem, no .., under /workspace) and again by the helper after resolving the parent directory. The final component is never followed: deleting or renaming a symlink acts on the link. An ancestor that is a symlink is path_refused in the overlay (the snapshot index shows it) and is resolved-and-contained in the helper (a link that leads out of the workspace is refused as for any file operation). A .git segment in path, from or to, lexical or resolved, is path_refused; a recursive delete of a directory that contains a .git directory below the named one is allowed (it removes, it does not inject). The workspace root and the home of the browser profile cannot be deleted or renamed. Excluded directory names (L40) are refused by the overlay as not_in_saved_copy and are allowed on the live path. A recursive removal never crosses a mount (st_dev is checked) and never follows a link.

7.8.8 Audit

Records of section 7.1 with operation delete, move or mkdir; path is the source, to_path the target of a move; recursive and removed (the count) for a delete; sha256_before or tree_sha256_before from the If-Match; source live or overlay; no content. Refusals (a .git path, owner_role_required after authentication, a failed precondition) are audited as for a write; the idempotent mkdir of an existing directory is not. The owner's overlay_apply records name the operation and the outcome (ok, already, conflict with its reason).

7.8.9 Size and cost

Caps in L41 and L62. A delete, a move and a mkdir are index-only: no blob, no content bytes. Cost in section 19.

8. The file helper

conversation/src/pi/owner-file-helper.ts gains operations and fields. Only Node built-ins and @chatticus/host-protocol/live-file-rules are imported (the rules module imports nothing).

export type OwnerFileOperation = "read" | "write" | "stat" | "realpath" | "list";

export type OwnerFileRequest = {
	readonly operation: OwnerFileOperation;
	readonly path: string;
	readonly allowedRoots: readonly string[];
	readonly contentBase64?: string;               // write (Pi tools)
	readonly content?: string;                     // write (live): UTF-8 text
	readonly precondition?: { type: "if_match"; sha256: string } | { type: "if_none_match" };  // write
	readonly createParents?: boolean;              // write: mkdir -p, the Pi tools only
	readonly refuseGitSegments?: boolean;          // every live request
	readonly range?: { offset: number; length: number; maxFileBytes: number; mask: boolean };   // read: absent means the whole file, as today
	readonly maxEntries?: number;                  // list
	readonly maxScan?: number;                     // list
};

The response keeps the shape of today's (ok with fields, or ok: false, code, message) and gains entries, resolvedPath (logical, /workspace/...), sha256, sha256Before, modifiedMs, mode, created, keptAs, currentSha256, truncated, masked, binary, encoding, size, offset, length, content. Error codes are LIVE_FILE_OWNER_ERROR_CODES; the existing CHATTICUS_OUTSIDE_WORKSPACE is mapped to outside_workspace, ENOENT to not_found, EACCES and EPERM to permission_denied, anything else to io_error. UnprivilegedExecutionEnv's CODES map (pi/unprivileged-execution-env.ts) keeps working through the same table.

Every operation first resolves the final location (finalLocationOf, as today), asserts it inside allowedRoots, and if refuseGitSegments asserts the resolved path has no .git segment (path_refused). Every operation maps the real path back to /workspace/... for resolvedPath.

list. The resolved path must be a directory (not_a_directory). opendir, read at most maxScan names (20,000), lstat each, sort directories first then by name (the Phase 1 order), keep maxEntries. A symlink entry carries link_target from readlink (4096 characters at most). A FIFO, socket or device is left out. truncated is true if names beyond the cap exist. Entries carry modified_at, mode, size (files), no hash.

stat. lstat of the final component without following it, after the containment check of its parent (today's behavior), returned as an entry.

read. Resolve, containment. Open the resolved path with O_RDONLY | O_NONBLOCK; fstat must say regular file (not_a_file) of at most maxFileBytes (file_too_large). Read it whole, hash it (SHA-256, hex), take the range, sniff binary with looksBinary, trim a text range to a character boundary. If mask is true and the resolved path or the requested path looks secret, return masked: true with size and sha256 and no content (the same as the snapshot's masked answer). With no range the whole file is returned as base64 and no cap applies: that is the Pi read_workspace path, unchanged.

write. In this order:

1. Resolve and contain. if_none_match: lstat the final location must be ENOENT else already_exists. Creating needs the parent directory (parent_missing) unless createParents.
2. if_match: open the final location O_RDONLY | O_NONBLOCK, fstat regular (not_a_file) and at most 256 KiB (file_too_large), hash. Different: precondition_failed with currentSha256. Keep this descriptor open.
3. Create .<name>.chatticus-<32 random hex>.tmp in the resolved directory with O_WRONLY | O_CREAT | O_EXCL | O_NOFOLLOW, write the bytes, fsync, fchmod to the old file's permission bits (0664 for a new file).
4. Compare again immediately before publishing: if_match: hash the file at the final location again; if_none_match: lstat again. A difference unlinks the temporary file and answers precondition_failed or already_exists.
5. Publish: rename(temp, final) for a replace; link(temp, final) then unlink(temp) for a create (EEXIST is already_exists).
6. Post-check (replace only): re-hash through the descriptor of step 2, which still reads the replaced inode. If it differs from the expected hash, someone wrote that inode in place between steps 4 and 5. Write its bytes to <final>.chatticus-replaced-<8 hex> (the shell user's own file, in the same directory) and answer ok with keptAs.
7. Answer created, size, sha256Before, sha256 (of the new bytes), modifiedMs.

On every failure after step 3 the temporary file is unlinked. A helper killed by its timeout can leave .chatticus-*.tmp behind; it is visible in a listing and harmless (YAGNI: no sweeper). The window that remains is the time between step 6's read and the end of the helper (a write into the replaced inode after the post-check): microseconds, and the result is the same as a shell redirect landing a moment after a save.

The Pi tools' write (UnprivilegedExecutionEnv.writeFile) calls this operation with contentBase64, createParents: true, no precondition and no refuseGitSegments: it now writes atomically (a reader never sees half a file). The existing scenarios of computer_owner_file_isolation.feature stay green and are the proof that the link rules did not move.

8.1 Helper operations for delete, rename and new folders (revision 3)

OwnerFileOperation gains mkdir, unlink, rmtree and rename; the request gains to (rename), recursive, and one precondition field, sha256, the effective hash the entry must have (a file's content hash, a link's link hash or a directory's tree hash); the helper decides which by the entry's real kind, so the caller never has to know it. All of them: resolve the parent directory of each path they name (finalLocationOf) and assert it inside allowedRoots; never follow the final component; refuse a resolved .git segment when refuseGitSegments; answer with the codes of LIVE_FILE_OWNER_ERROR_CODES.

• mkdir: the parent must exist (parent_missing); mkdir with mode 0775 through the launcher's umask; EEXIST on a directory is ok with created: false, on anything else already_exists.
• unlink: lstat the final component. A file: open O_RDONLY | O_NONBLOCK, fstat regular, hash, compare with the precondition (precondition_failed with currentSha256), unlink, then re-hash through the held descriptor; if it differs from the expected hash (an in-place writer in the window), write those bytes to <name>.chatticus-deleted-<8 hex> beside it and answer ok with keptAs. A symlink: compare the symlink hash (L49), unlink. A directory: rmdir; directory_not_empty if it has children.
• rmtree: only with recursive and a sha256 that is the tree hash. Walk with lstat (never following a link, staying on the starting device, at most 5000 entries, else too_many_entries), compute the tree hash, compare (precondition_failed with the current tree hash), then remove depth first with unlink and rmdir. A tree that contains a .git directory below the named path is removed (L59).
• rename: lstat the source without following; compare the precondition (the content or symlink hash, or the tree hash of a directory); the target's parent must exist and the target must not (already_exists); the target must not lie inside the source (invalid_move); same device. A file or symlink: link(source, target) (it fails if the target exists) then unlink(source); the inode is the same, so an in-place writer in the window loses nothing. A directory: mkdir(target) exclusively, then rename(source, target), which replaces only the empty directory just made; ENOTEMPTY or EEXIST removes the made directory and answers already_exists.
• stat with hash: true returns the effective hash: treeSha256 for a directory (too_many_entries past 5000) and sha256 for a regular file of at most maxFileBytes (the live read limit, 8 MiB; a larger file is file_too_large). A link's sha256 (its link hash) is always returned.

Pi's own file tools do not use these operations. The supervisor's file runner (9.1) maps request kinds delete, move and mkdir to them and passes refuseGitSegments: true.

9. The supervisor (container)

All in computer/host/src/. The bundle must not import Pi, UnprivilegedExecutionEnv, the starter or the owner stores (computer-image-structure.test.ts). scrubbedShellEnvironment (conversation/src/pi/local-computer-tools.ts) is moved, unchanged, to conversation/src/pi/shell-environment.ts (no imports beyond Node) and imported by both.

9.1 The file runner

New live-file-operations.ts, class LiveFileOperations, with ports so a scenario supplies fakes:

export interface FileHelperLauncher {
	/** Run the helper once with this request on standard input; kill it at the timeout; resolve with its parsed answer or a helper error. Never rejects. */
	run(request: OwnerFileRequestToHelper, timeoutMilliseconds: number): Promise<OwnerFileResponse>;
}

export type LiveFileOperationsOptions = {
	readonly launcher: FileHelperLauncher;
	readonly postResult: (operationId: string, outcome: LiveFileOutcome) => Promise<"recorded" | "closed">;
	readonly clock: SupervisorClock;
	readonly log: LogEmitter;
	readonly workspaceRoot: string;
	readonly memoryUsedPercent: () => number | undefined;
	readonly onFinished: (kind: OwnerFileRequest["kind"], outcome: LiveFileOutcome) => void;
};

ProcessFileHelperLauncher (live-file-helper-launcher.ts) starts <launcher> -c 'exec "$@"' chatticus-file-helper <node> file-helper.mjs with cwd = workspaceRoot and the scrubbed environment, writes the JSON request to standard input, reads at most 1 MiB of standard output, and at the timeout sends SIGKILL to the process group. It does exactly what UnprivilegedExecutionEnv.ask does and nothing else; it never opens a path itself.

LiveFileOperations.accept(requests), called by the supervisor for each poll answer:

• A request id already known (running, queued, or finished within the last 60 seconds) is ignored; a finished one whose post failed is posted again.
• Stopping: the answer is error owner_stopping. Memory at or above 90 percent, or more than 8 queued: owner_busy.
• Otherwise queue; at most 2 helpers run. A queued request whose expires_in_ms (measured from receipt on the monotonic clock) lapses before it starts is answered expired without touching the disk.
• The request is turned into a helper request: refuseGitSegments: true; read gets range: { offset, length, maxFileBytes: 8388608, mask }; list gets maxEntries and maxScan: 20000; write gets content, precondition.
• The helper's answer is validated against liveFileOutcomeSchema; one that does not parse is helper_failed. A timeout is helper_timeout.
• The result is posted with up to 3 attempts, 1 second apart, on a network error or a 5xx. closed (409 operation_closed) drops it. A 401 or a superseding 403 ends the supervisor as superseded, as for a poll.
• onFinished lets the supervisor restart its idle clock (L12) and, for an ok write, schedule the quiet publish (L13).

pause() and resume() and stopAccepting() are L17. A paused runner queues; it does not answer. stopAccepting() is called first thing in performStop and in the SIGTERM path.

9.2 Supervisor changes

• OWNER_PROTOCOL_VERSION becomes 2.
• onPollAnswered hands response.file_requests to accept. File requests are accepted in every state except booting and hydrating: the supervisor answers those owner_busy (the server does not deliver in those states; this is the belt).
• onChildExit: await files.pause(); try { await sweep } finally { files.resume() }.
• performStop: await files.stopAccepting() before terminateChild.
• On onFinished: if the state is idle, startIdleClock() (an owner_idle line restarts the count); for a write, nextPublishCheckAtMilliseconds = min(existing, now + OWNER_QUIET_PUBLISH_SECONDS * 1000). While a child runs the publish stays deferred (C14).
• protocol-client.ts: OwnerSupervisorClient.postFileResult(request) with ownerFileResultRequestSchema and ownerFileResultResponseSchema, the same headers and error handling as poll.
• supervisor-main.ts wires ProcessFileHelperLauncher, fileHelperCommand ([process.execPath, join(dirname(import.meta.url), "file-helper.mjs")], as owner-main.ts:23 does) and containerMemoryUsedPercent.

9.3 Logs

One line per operation, from the supervisor, never a path, a name or a byte of content: file_operation: kind, bytes, path_hash (first 12 hex of SHA-256 of the path), source (live), outcome (ok or the error code), duration_ms, queue_ms. Other lines: file_operation_refused (reason: owner_stopping, owner_busy, expired), file_operation_post_failed (status or error_name, attempt). Front Door lines (no content, no path): file_op_queued, file_op_abandoned, file_op_delivered, file_result_recorded, file_result_refused code=<code>, file_audit_failed, file_rate_limited class=<class>.

9.4 The overlay at hydrate (revision 2)

Files: computer/host/src/overlay-applier.ts (new), host-disk-lifecycle.ts, supervisor.ts, supervisor-ports.ts, protocol-client.ts, supervisor-main.ts. The applier uses the same FileHelperLauncher as the file runner (9.1); it never opens a workspace path itself.

export interface OverlayApplier {
	/** Seal the overlay, apply its entries through the file helper, report conflicts. Resolves with the entries now on the disk. Throws OverlayApplyError (the hydrate fails, exit 8). */
	applyAfterHydrate(): Promise<{ readonly applied: readonly OverlayEntryReference[]; readonly conflicts: readonly OverlayEntryReference[] }>;
	/** After a recorded publish: ask the Front Door to clear exactly these entries; true when acknowledged. */
	clearApplied(entries: readonly OverlayEntryReference[]): Promise<boolean>;
}

• SupervisorPlane gains sealOverlay(request) and postOverlayApplied(request) (OwnerSupervisorClient, same headers and error handling as poll).
• HostDiskLifecycle.hydrate(): after bootThroughWorkspace() and afterHydrate (the group sharing that lets uid 2000 write), call applyAfterHydrate() inside the budget of OVERLAY_APPLY_BUDGET_SECONDS; the entries it applied are returned to the supervisor.
• OwnerSupervisor: keeps appliedAwaitingClear. In beginHydration, after disk.hydrate(), sets nextPublishCheckAtMilliseconds to now + OVERLAY_EARLY_PUBLISH_SECONDS when entries were applied (else the 600 second default of today). beginPublishCycle and the final publish of performStop capture the set before the pack starts and call clearApplied after publishChangedDisk succeeds; needsPublish() === false right after the apply clears at once. A failed clear is retried on the 10 second tick (OVERLAY_CLEAR_RETRY_SECONDS) and up to 3 times before the stopped report; it never blocks the stop.
• Failure rules: a 401 or a superseding 403 on either route ends the supervisor as superseded (as for a poll); a 5xx or a network error on the seal is retried inside the 30 second budget, then snapshot_skipped reason=overlay_failed and exit 8; a blob that cannot be read or does not hash to its entry, or a helper failure other than precondition_failed, is the same.
• Logs (no path, no content): overlay_sealed (entries), overlay_applied (applied, already, conflicts, duration_ms), overlay_clear_requested (entries), overlay_cleared (remaining), overlay_apply_failed (reason).

10. The web app

Files: web/lib/computer-files.ts, web/lib/computer-files-api.ts, web/lib/touched-files.ts, web/components/workspace/ComputerFilesPanel.tsx, web/components/workspace/ComputerFilesView.tsx, the fixtures and tests beside them. Read docs/BRAND_GUIDELINES.md before touching a background, region or border: the new banners are flat surfaces like the existing notices, with no new border. The web app does not import host-protocol (it is not a dependency of web/); it mirrors the JSON of section 5.2 in its own types, and the @web scenarios are what keeps the two honest.

10.1 What the panel shows

FileListing.source and FileContentRange.source widen to "snapshot" | "live"; both gain stale, fallback_reason, retry_after_ms?; content gains revealed, editable, modified_at, overlay, mine_sha256?; an entry gains modified_at and overlay. The write response gains source: "overlay" and a boolean backed_up.

10.2 The watch ping

While the Files tab is the visible inspector tab and document.visibilityState === "visible", the panel posts /computer/files/watch { open: true } on mount and then every 15 seconds. When the tab is hidden, switched away from or unmounted it posts { open: false } once (best effort, fetch with keepalive; the 45 second window is the guarantee). The answer drives the source line before any file is read. A 429 stops the ping for a minute. The ping carries no content and no path.

10.3 Reading while live

No timer re-reads a listing or a file (design non-requirement 6). The panel re-reads in these cases only: the member navigates, opens or refreshes; a tool call of the running turn names the open directory or file (touched-files already collects write_workspace, edit_workspace and read_workspace paths from the tool cards; the panel re-reads an open, unedited file or listing when its entry changes); and the editor probe below.

10.4 Edit mode

Offered when the content response has editable: true, as a button Edit beside Copy. The text area is plain monospace text, the whole file (a file over 256 KiB or truncated shows This file is too large to edit here and no button). State, a pure function in web/lib/computer-files-edit.ts (vitest):

viewing -> editing(loadedSha256, loadedText, draft) -> saving -> saved -> viewing(new sha256)
                                    |                      |
                                    |                      +--409 precondition_failed--> conflict(currentSha256, theirText, draft)
                                    +--changed on the computer--> editing + warning(piChanged)

• Save sends PUT with If-Match: "<loadedSha256>" and { content: draft }. While saving, the button is disabled and the status reads Saving. 200 with source: "live": Saved on the computer, with the line Not yet in the saved copy (backed_up is false); 200 with source: "overlay": Saved. Your change will be applied when the computer starts, with no line about the saved copy (backed_up is true). The new sha256 becomes loadedSha256 and the file leaves edit mode. kept_as present: a notice A change made at the same moment was kept as <name>.
• New file: in a live listing a New file button asks for a name (must not contain /), creates it with If-None-Match: * and an empty draft, and opens the editor. 409 already_exists: A file with that name exists.
• Leaving (Back to folder, opening another file, navigating, the tab switching away) with a changed draft asks Discard your changes? with Keep editing and Discard. Reload with unsaved changes asks the browser's own prompt.
• Errors keep the draft: owner_warming and owner_timeout (Could not reach the computer; your text is kept, Retry), outcome_unknown (Not sure the save happened. Reload the file to check, with a Reload button that reads the file and shows the conflict banner if it differs from the draft), rate_limited, computer_starting and computer_stopping (The computer is starting; your text is kept, tried again automatically after retry_after_ms, three times, then a Retry button), owner_too_old (The computer is being updated; try again in a few minutes), overlay_full (Too many files were edited while the computer was off; start the computer or discard some), not_in_saved_copy (This folder is not kept in the saved copy), edit_unsupported (Files on this computer cannot be edited here), content_too_large, file_too_large, path_refused, precondition_required (a bug, shown as a generic error).

10.5 The conflict banner

An overlay conflict (the content response says overlay: "conflict") shows the same banner on open, with the text Your edit conflicts with a newer version of this file, the saved version (theirs, the response) and the person's text (variant=mine), and the buttons Overwrite with mine (a PUT with If-Match of theirs), Use theirs (the discard route, after the discard prompt) and Copy mine.

On 409 precondition_failed the panel reads the current file (GET /content, live) and shows a banner above the editor: This file changed on the computer while you were editing. with the other version beside the member's draft (two read-only panes on a wide viewport, stacked on a phone), current_sha256 as the new base, and three buttons: Overwrite with mine (PUT with If-Match of current_sha256, an ordinary audited write), Use theirs (drops the draft after the discard prompt), Copy mine. The draft is never lost without a click. There is no merge.

10.6 Pi changed this a moment ago

A non-blocking notice above the editor, with a Show their version button that opens the same comparison as the banner. It appears when either:

1. a tool card for write_workspace or edit_workspace whose normalised path equals the open file appears or changes status, in the live turn or the last committed message, within the last 60 seconds of the browser's clock (ToolCardModel has no timestamp; the panel stamps the time it first sees a card, and collectTouchedFiles returns a lastCallId per path so a second write to the same path is a change); or
2. the editor probe finds a change. While a file is in edit mode the panel calls GET /stat?path= every 5 seconds (LIVE_FILE_EDIT_PROBE_SECONDS; paused while the tab is hidden) and compares size and modified_at with the values at load. The probe catches a shell command (git checkout, sed -i) that no tool card names. Each probe is a file request through the poll channel: about 12 a minute against a limit of 240.

Tool events carry the model's path as typed, up to 500 characters (conversation/src/turn/tool-event-fields.ts:12) and argumentsTruncated when cut; a truncated or unnormalizable path is not matched (the probe is the safety net).

10.7 Masked files

A masked content response shows the existing This file looks like it holds a secret and is not shown and a Reveal button. It opens a confirmation: Showing this file is recorded in the audit log, with your name and the time. with Reveal and Cancel. Confirmed: POST /reveal, the text is held in component state only (never in storage, never in the URL), shown with a Hide button, cleared on Hide, navigation, tab switch and unmount. A revealed file may be edited (the same If-Match of its revealed sha256); every save is audited like any other.

10.8 Accessibility and phone width

Controls keep the 44 pixel minimum used by the existing buttons (min-h-11); the source line and the status messages are aria-live="polite"; the conflict banner is role="alert"; focus moves to the banner when it appears and back to the Save button after a choice; every state has text, not only colour. At 375 pixels the two-pane comparison stacks and the editor uses the full width.

11. State machines

11.1 A file request item (server)

(none) --queue (transaction)--> pending --deliver (poll)--> delivered --result route--> done --Front Door reads--> (deleted)
                                   |                            |                          |
                                   +--abandon (Front Door)--> abandoned          waiter_gone: result route deletes
                                   +--expires_at--> (absent to every reader)

Events that do nothing: a result for abandoned, pending or absent (409 operation_closed); a second identical result for done (200); a second different result (409). Only one owner id ever holds a request: the one named on the item at queue time.

11.2 One request inside the supervisor

received --(known id)--> ignored | re-post stored result
received --(stopping)--> answered owner_stopping
received --(busy / queue full / memory)--> answered owner_busy
received --> queued --(expires_in_ms lapsed)--> answered expired
queued --> running --> answered --> posted --> remembered 60 s
                          `-- helper timeout (6 s) --> answered helper_timeout

pause() holds queued requests back from running. stopAccepting() answers new ones owner_stopping and waits for running.

11.3 One member request (Front Door)

GET:  authenticated -> limited -> source chosen -> [snapshot answer]
                                              `-> queued -> waiting -> done -> answered live
                                                              |-> abandoned -> snapshot answer (stale)
                                                              `-> delivered, no result in 8 s -> snapshot answer (stale), waiter_gone
PUT:  authenticated -> limited -> headers/body/path ok -> live? -> audit pending -> dirty -> queued -> waiting
         -> done: ok -> 200 | conflict -> 409 | other error -> mapped
         -> abandoned -> 504 owner_timeout (audit failed)
         -> delivered + 7 s more -> 504 outcome_unknown (audit stays pending; the result route finishes it)

11.4 Audit outcome

pending -> ok | conflict | refused | failed; pending read after 120 seconds is unknown. A refused record is written directly (path_refused) and never passes through pending.

11.5 Interactive window

interactiveUntilAt is set by a watch ping (+45 s), by queueing a request (+45 s) and cleared by open: false (= now). The poll reads it: before it, the owner is told the interactive pace in states that can serve files; after it, the normal tier. It is removed with the owner fields when the owner ends.

11.6 The panel

connecting (watch ping sent) -> live | saved-copy (off) | starting | warming -> (retry timer) -> live; live -> fallback on a stale answer -> retry -> live. Editing exists only inside live; a transition out of live while editing keeps the draft and disables Save until live.

11.7 The overlay entry and the seal (revision 2)

(none) --member edit (swap)--> pending --member edit--> pending (revision + 1)
          pending --snapshot hash becomes entry hash (a publish by the owner)--> applied --clear (route)--> (none)
          pending --snapshot hash is neither base nor entry (a host that ignores the overlay)--> conflict
          pending|conflict --discard (swap)--> (none)
          conflict --member edit with If-Match of theirs (swap)--> pending (base = theirs)
          pending --owner finds a third hash on the disk--> conflict (stored)

unsealed --owner seal (swap)--> sealed(owner, generation, snapshot_generation)
sealed --stopped report (swap)--> unsealed
sealed --owner no longer live (heartbeat lapsed, newer generation)--> stale (replaced by the next seal or member write)

An entry is cleared only from the sealed state and only when a publish is on record (L37). Member writes happen only from unsealed or stale.

12. Security

12.1 What is protected, and from whom

Members of an organization share one workplace; every enabled member may read and write (D8). What must hold: a non-member reaches nothing; the owner (root, holding the snapshot credentials) never opens a path a person or the model named; the trail of edits cannot be edited by the owner or by the shell; a request cannot be replayed to another computer or another owner; and the owner cannot be made to run out of memory or time by a member.

12.2 Confused deputy

12.3 Symlinks and the time-of-check to time-of-use windows

1. Path check to open (planted or swapped link). Closed by the privilege boundary, not by the check: the helper is uid 2000, so a link swapped between the check and the open leads where the shell could already go (owner-file-helper.ts header). The containment test and the .git and secret tests on the resolved path are a second line and the reason the behavior is testable on a machine with no second user.
2. Special files. O_NONBLOCK and fstat regular-file check remove the hang of a FIFO or a device (L15); a file swapped for a FIFO after the check is opened with O_NONBLOCK and refused after fstat.
3. Precondition to rename. The helper compares the hash, writes the temporary file, compares again, then renames. A concurrent writer that writes the same inode in place (the shell >, Pi's former in-place writeFile) between the second comparison and the rename is detected by the post-check through the descriptor held since the first read, and the replaced bytes are kept beside the file (kept_as, L16). The residue is a concurrent writer that replaces the file by rename inside that same few-microsecond window: its file is a complete file and ours replaces it, which is what two people saving a moment apart without a lock produce. Node has no atomic exchange-if-unchanged, so this is stated, not closed. A change made after the post-check is indistinguishable from a change made a moment after the save.
4. Delivery to abandonment. A write the Front Door gave up on must not run later. The request is delivered only by a conditional update pending -> delivered; the Front Door abandons only by pending -> abandoned; exactly one wins. A delivered write the Front Door stopped waiting for is reported outcome_unknown, never "not done".
5. Queue to stop. Closed by the token on the computer record and the transaction (L11); the stop sequence finishes the operation in flight (L17), so an accepted edit is in the final publish.
6. Membership removed. The 30 second membership cache lets a removed member write for up to 30 seconds. Accepted and stated (L24).
7. Temporary file names. Random 128 bit names and O_EXCL | O_NOFOLLOW: the shell cannot pre-plant the name.

12.4 A compromised owner

An attacker who holds the supervisor token (a stolen token inside its hour, or code running in the container with the token) can: delay, drop or fail any file request (availability, visible as fallbacks and owner_timeout); return invented file content to the member (display only: text through React, images from a fixed list of types, SVG and HTML as source; nosniff); report wrong hashes (the audit records the Front Door's computed sha256_after and flags a mismatch; a wrong current_sha256 only makes a conflict confusing); read every request the poll gives it, which includes the content of a member's edit and, for a reveal, nothing more than the owner could already read from the disk. It cannot: read or write the audit family or the request family in the table (the supervisor role has no DynamoDB access; no owner route returns an audit record; the per-turn role does not list those partitions); obtain a request for another organization, computer or owner (the poll queries one partition for one owner id and generation); forge a member's identity. A compromised per-turn child (it holds turn credentials and may write T#computer#record, W25) can set interactive_until_at and file_operation_id on the record: it can make the owner poll fast (cost) or delay an idle stop; it cannot queue a request, forge a result or touch the audit. Scenarios "The owner cannot read the audit log" and "The owner cannot read or write the file operation records directly" evaluate both policy files (owner-role-policy.json, supervisor-role-policy.json) against the key families with the existing IAM evaluator (features-support/iam-policy-evaluator.ts).

12.5 Denial of service through file operations

12.6 Secrets and data at rest

File content passes through the table for at most the length of a request and is deleted by the code that reads it (L10); the audit holds hashes and sizes, never content; the browser holds a revealed secret in memory only. Logs carry a 12 hex digit hash of the path, never the path or the content (the redaction rule of owner-main.ts:39-41 extended). Masked answers still carry the whole-file sha256 (as Phase 1's do): a member can reveal anyway, so the hash gives no member a capability, but an offline guess of a weak secret from its hash is possible; accepted (O4). Tokens never appear in file routes: the member's bearer is verified and dropped.

12.7 Findings, status

12.8 The edit overlay (revision 2)

Who may write. The Front Door alone. Exact statements:

The Front Door role (CDK, infra/lib/control-plane-stack.ts, beside ReadComputerSnapshots; the bucket is the snapshot bucket):

{
	"Sid": "WriteComputerEditOverlay",
	"Effect": "Allow",
	"Action": ["s3:PutObject", "s3:DeleteObject"],
	"Resource": ["arn:aws:s3:::SNAPSHOT_BUCKET/tenants/*/computers/*/overlay/*"]
}

s3:GetObject on tenants/*/computers/*/* and s3:ListBucket on the bucket already exist. The statements are the file conversation/src/gateway/front-door-snapshot-policy.json, read as data by the CDK stack (frontDoorSnapshotPolicyStatements) and by the scenarios of features/front_door_snapshot_role_policy.feature.

Why the list statement has no s3:prefix condition. S3 answers a GetObject of a key that does not exist with 404 NoSuchKey only when the caller holds s3:ListBucket on the bucket; without it the answer is 403 AccessDenied. That permission is evaluated for the read with no s3:prefix key in the request, so a statement conditioned on s3:prefix never applies to it. The first deployment carried StringLike s3:prefix tenants/*/computers/*/, so reading overlay/index.json of a computer with no overlay yet answered 403, the Front Door reported overlay_unavailable (503), the owner seal route failed and every hydrate ended overlay_apply_failed with reason seal_failed. The least privilege that works is s3:ListBucket on the bucket ARN with no condition, on the Front Door role only: it lets that role see key names (never object content) of the bucket, and the same role can already read every object under tenants/*/computers/*/*. A prefix condition cannot narrow it, because a caller who omits the prefix is not constrained by it. The scenario The Front Door reads a missing object as not found fails when the list statement is conditioned or removed. IAM is not enforced by moto, so this is proved by the evaluator rule objectReadOutcome, not by the store tests. Conditional puts need only s3:PutObject. s3:DeleteObjectVersion is not granted, so a delete leaves a delete marker and the earlier version (see "Secrets" below).

The supervisor role (conversation/src/gateway/supervisor-role-policy.json, read as data by infra/lib/owner-role-policy.ts and evaluated by the scenarios): the existing SnapshotObjects allow stays (GetObject covers reading the overlay; PutObject and AbortMultipartUpload are what the pack upload needs), and a second statement is added:

{
	"Sid": "OverlayIsWrittenByTheFrontDoorOnly",
	"Effect": "Deny",
	"Action": ["s3:PutObject", "s3:DeleteObject", "s3:DeleteObjectVersion", "s3:PutObjectTagging", "s3:AbortMultipartUpload"],
	"Resource": ["{{snapshotBucketArn}}/tenants/${aws:PrincipalTag/tenant}/computers/${aws:PrincipalTag/computer}/overlay/*"]
}

An explicit deny wins over the allow whatever else is attached. The supervisor therefore reads the overlay and can neither write nor delete in it; it never holds a delete right at all. The "delete only applied entries" of the brief is done by the Front Door at overlay-applied, which can check what IAM cannot: that the entry still matches by path and revision, that the seal is valid, and that a publish is on record (L37). features-support/iam-policy-evaluator.ts (type Effect: "Allow" only today) learns Deny with the rule that a matching deny overrides any allow; infra/lib/owner-role-policy.ts passes Effect through. The per-turn role has no snapshot statement; the scenario proves it against overlay/index.json and a blob key.

What a compromised supervisor (token and credentials) can do. Read the overlay of its own computer (it holds the files anyway). Claim cleared for entries: refused unless the seal is its own and a publish is on record; the worst case is clearing an entry whose publish it faked, which needs the disk it already controls. Report false conflicts: an entry the person sees as a conflict, and nothing is lost (the person's text stays readable). Refuse to apply: the person's edit waits (availability). It cannot write, delete or replace an overlay object, cannot seal for another computer (the route authenticates the owner and the key is built from the token's tenant and computer), and cannot read another computer's overlay (the role's prefix is tag-bound).

Confused deputy. The Front Door writes the overlay for a member into the prefix built from principal.tenantId and the computer record, never from the request; blob keys are hashes; no member-chosen string is an S3 key. The owner applies entries through the file helper as uid 2000 with the base-hash precondition, refuseGitSegments and the containment check, so an entry for /workspace/leak where leak is a link out of the workspace is a conflict, not a write (scenario "The overlay is applied through the file helper and cannot reach outside the workspace"). Root never opens a workspace path.

Time of check to time of use. The seal swap is the linearization point (R1). Between the owner's blob read and the helper write, the disk cannot change under it: no turn runs and no file operation is delivered before the supervisor leaves hydrating. A blob is verified against its hash before it is written.

Denial of service. Caps (L41); 30 writes a minute a user (the write counter); at most 3 swap attempts per request; an index of at most 256 KiB read per request; an apply bounded to 30 seconds with the failure meaning "the owner does not start" rather than "the agent runs without the edits" (a person who keeps an overlay unreadable can only hurt their own organization's computer, and the control plane's start lease and probes behave as for any hydrate failure).

Secrets. Overlay content is stored as plaintext objects under the bucket's managed encryption (S3_MANAGED, enforceSSL), deleted when cleared. Masking by name applies to overlay content; a reveal is audited (source overlay); the audit never holds content.

Why a lifecycle rule on non-current versions (L63), in plain words. The snapshot bucket has versioning on (infra/lib/snapshot-stack.ts). Versioning means S3 keeps every object that is overwritten or deleted, as a hidden older version, and keeps it until someone deletes it explicitly. Today every publish overwrites the single pack snapshot.tar.gz (and manifest.json), so each older version is a complete copy of the whole workspace as it was at that publish; it is not a per-file history and the product never reads it. Nothing expires them, so they only accumulate: a storage cost that grows with every publish, and an administrator's recovery window (the way back from a bad publish). The overlay adds small deleted blobs to the same pile, and an edited .env that was cleared would stay recoverable there. Neither a product feature nor a promise. The rule, in part B: expire non-current versions 30 days after they stop being current (noncurrentVersionExpiration: Duration.days(30) on the bucket). Effects: storage stops growing without bound; an administrator can still restore a version for 30 days; after that a deleted overlay secret is gone. It does not touch the current pack, the current manifest or live overlay objects.

Customer-account computers (L46). Exactly why they are read-only: they run in the customer's own AWS account through the older host-worker path, with the customer-owned bucket chatticus-snapshots-{OrganizationId}. The Front Door's overlay write grant (WriteComputerEditOverlay) names only the Anthus snapshot bucket, so it cannot write there, and the host that would apply an overlay is a host worker with no supervisor: nothing seals, applies or clears. Making them editable needs three things the later-phase ticket carries: a cross-account write grant for the Front Door through the existing customer role, the same overlay protocol in the host worker, and the lifecycle rule in the customer's stack.

The other writer to the prefix. LocalWorkerRole (snapshot-stack.ts, grantReadWrite on the whole bucket) can write any object, overlay objects included. By the owner's decision (O7) it is left as it is: it is the role the operator's local hosts assume, it already has read and write on the whole bucket, and it is operator-trusted, outside the owner roles this section is about. It is noted here so that nobody reads the explicit deny on the supervisor role as a bucket-wide guarantee.

Audit. Every overlay edit and discard has a record before any object is written (L44); every owner-reported clear and conflict has an overlay_apply record. No owner role reads the audit.

13. Traceability

Scenario names are those of the registered computer_file_*.feature files and web_computer_files.feature: computer_file_live_member and computer_file_live_operations (server routes), computer_file_live_owner (the owner routes), computer_file_overlay and computer_file_overlay_authority (the overlay, store level and who may write it), computer_file_live_supervisor and computer_file_overlay_supervisor (the supervisor), web_computer_files (the panel) and computer_file_live_end_to_end (the whole path); the draft file that held them has been deleted. Tags: @server (A1, A2), @supervisor (C), @web (W), @end-to-end (E). vitest is the unit-test exception of AGENTS.md: pure helpers only.

Unit tests (vitest), the exception of AGENTS.md: the overlay merge (overlay-merge: applied, pending and conflict states for the four operations, list ordering and cap, the tree hash and the symlink hash, path translation under a moved directory), the write algebra of 7.8.4 as a pure function of (entries, request) with a table-driven test of every row, the apply order of 7.8.5, the overlay index schema, the swap loop with a fake store that fails the condition, the seal and clear rules as pure functions of (index, computer record, request); live-file-rules (livePathProblem, normalizeLivePath, livePathHasGitSegment, looksLikeSecretFile, looksBinary, trimToCharacterBoundary); the schemas of section 5.2 (including the item size test of L20 and the unknown-field rules); ownerFilePanelPace; the expected-pickup arithmetic of L27; the helper's atomic write with an injected hook between the second comparison and the rename (the post-check keeps the replaced bytes; the temporary file is removed on every failure; the create is exclusive); the runner's queue and mutex with a fake launcher and clock; the audit and request codecs; the store contract test (conditional updates, transaction, expired items ignored, waiter_gone); web/lib/computer-files-edit.ts and touched-files.ts. None of these duplicates a Gherkin scenario: each is a pure function or a codec.

14. Open questions for the owner

The owner's answers close the earlier questions (section 3.0, O1 to O7). Two choices were made in revision 3 where the brief was silent; they are written down for confirmation, and nothing else is open.

• Q-P1. A rename never replaces an existing path (L52). The alternative is an explicit overwrite. Recommendation: keep it refused; the person deletes first. It removes a way to lose a file silently, and the overlay and the helper both rely on an exclusive target.
• Q-P2. A pending folder rename or recursive delete is exclusive (L53): other changes at or under it wait (409 path_busy) until the next owner applies it or the person discards it. The alternative is composing path translations across several renames. Recommendation: keep exclusive; it keeps the apply a single rename.

15. Work assignment

Everything is a pull request into develop with the Gherkin first (AGENTS.md). Steps for a draft scenario are written by whoever owns its tag; a scenario enters features/cucumber-features.txt together with its steps. This contract, the draft feature and the design document edits merge first. Do not read or write project/. Revision 2 adds infrastructure (part B), the overlay (parts A3 and C2) and splits the server and container work accordingly.

F0. Foundation (first, small; merged before the others integrate)

Files: host-protocol/src/live-file-rules.ts, live-files.ts (section 5), host-protocol/src/edit-overlay.ts (section 5.5); the exports and constants of section 5.3 in host-protocol/src/supervisor.ts (including overlay_not_sealed and the other new error codes) and host-protocol/package.json (./live-files, ./live-file-rules, ./edit-overlay); conversation/src/snapshot/files.ts (import the shared rules); tests conversation/test/live-file-rules.test.ts, live-files-protocol-schema.test.ts, edit-overlay-schema.test.ts, and the changes to owner-supervisor-protocol-schema.test.ts. Acceptance: typecheck, npm test, npm run test:features green with no behavior change except the shared secret name. Does not change OWNER_PROTOCOL_VERSION.

B. Infrastructure and policy (independent; deploy before A2 or C2 reach development)

(Revision 3: the lifecycle rule is part of this part, not optional: noncurrentVersionExpiration of 30 days on the snapshot bucket in infra/lib/snapshot-stack.ts with a test in infra/test, explained in 12.8. The Front Door statement WriteComputerEditOverlay also covers the deletes the clear performs.)

Files: infra/lib/control-plane-stack.ts (statement WriteComputerEditOverlay, 12.8), conversation/src/gateway/supervisor-role-policy.json (the deny statement), infra/lib/owner-role-policy.ts (pass Effect through), conversation/features-support/iam-policy-evaluator.ts (learn Deny), features/owner_role_policy.feature and computer_owner_policy_coverage.feature (the overlay rows), infra/test/computer-owner-stack.test.ts (assertions: Front Door can write only overlay/*, supervisor role has the deny and no delete), and infra/lib/snapshot-stack.ts (expire non-current versions after 30 days, L63; a CDK assertion in infra/test). Scenarios: LF-59. Acceptance: cd infra && npm test; cd conversation && npm run test:features. cdk deploy of the ThinTurn stack is by CI on develop.

A1. Server: store, domain, owner routes for file requests (needs F0)

Files: conversation/src/store/codecs/computer.ts, store/codecs/live-file-operation.ts (new), store/codecs/file-audit.ts (new), store/messaging-store.ts, store/dynamo-messaging-store.ts (queue transaction, deliver, abandon, complete, count, delete, audit put and finalize, incrementRateCounter, approveOwnerStop with the second guard, touchInteractiveWindow), features-support/in-memory-messaging-store.ts (the same), domain/computers.ts (recordHostSnapshotPublished and recordHostHydrated as targeted updates, L19, first commit of the part), domain/live-files.ts (new: liveFileSourceOf, expected pickup, ownerFilePanelPace, deliver, record result, finalize audit), domain/owner-supervisor.ts (poll delivery, cadence, stopVeto, approval token), http/owner-host-auth.ts (OWNER_COMPUTER_ROUTES), http/owner-supervisor.ts (ownerFileResultHandler), http/app.ts (declare the route). Tests: test/dynamo-messaging-store.contract.test.ts, test/owner-supervisor-domain.test.ts, test/route-audience.test.ts, test/owner-supervisor-client.test.ts if it lists routes. Scenarios it makes pass (steps in features-support/steps/live-files-owner.steps.ts, a FakeLiveOwner in features-support/fakes/): the "poll", "result", "fast poll", "idle stop" and "owner cannot read" scenarios (LF-15 server part, LF-21, LF-28 to LF-31). Acceptance: those scenarios and every existing owner scenario green.

The overlay (seal, clear, unseal in the stopped report) belongs to A3. A1 and A3 both add routes to OWNER_COMPUTER_ROUTES and http/app.ts; whichever merges second resolves a one-line conflict in http/owner-host-auth.ts and http/app.ts.

A3. Server: the overlay core and its owner routes (needs F0; independent of A1)

(Revision 3: the core covers all four operations. The write algebra of 7.8.4 as a pure function with a table-driven test, the merge of 7.8.3 including path translation under a moved directory, the tree hash and symlink hash of 7.8.2, the conflict derivation per operation, the clear shortcut of 7.8.5, and the GET .../files/overlay and discard-by-revision handlers.)

Files: conversation/src/snapshot/overlay-store.ts (new: the port with conditional get, put-if-absent and put-if-match; the S3 implementation with IfMatch and IfNoneMatch, the filesystem implementation with the same semantics for scenarios; first task: prove S3 conditional writes against moto 5.2.3 and note the result, L31), snapshot/overlay-merge.ts (new: the pure merge of 7.7.2 over LoadedIndex), snapshot/store.ts (the interface extension), domain/edit-overlay.ts (new: write with the swap loop, discard, seal, clear with the publish-on-record check, conflict marking, stale-seal rule, audit records), http/owner-host-auth.ts (OWNER_COMPUTER_ROUTES: overlay-seal, overlay-applied), http/owner-supervisor.ts (two handlers), http/app.ts (declare), http/routes/computer-file-overlay.ts (new: POST /overlay/discard), domain/computers.ts and the stopped-report handler in http/host.ts (unseal). Tests: test/overlay-merge.test.ts, test/overlay-store.contract.test.ts, test/edit-overlay-domain.test.ts. Steps: features-support/steps/edit-overlay.steps.ts (setup steps write through the domain function so A3 does not need A2). Scenarios: LF-53 to LF-56 and the store-level halves of LF-57. Acceptance: those green; the overlay contract test passes for both stores.

A4. Server: delete, rename and new folder routes (needs F0, A2 for the shared handlers and A3; revision 3)

Files: conversation/src/http/routes/computer-file-operations.ts (new: DELETE /files, POST /files/move, POST /files/directories, GET /files/overlay), http/app.ts (declare), domain/live-files.ts (the request kinds delete, move, mkdir through the same queue, wait, audit and abandon code as write), domain/edit-overlay.ts use (the overlay path), the role check (Principal.role === "owner" for recursive; 403 owner_role_required), the 428/409/413/422 mapping of 6.3, rate class write, audit operations delete, move, mkdir (7.8.8). Steps: features-support/steps/computer-file-operations.steps.ts. Scenarios: LF-65 to LF-72. Acceptance: those green; every earlier scenario unchanged.

A2. Server: member routes (needs A1 and A3)

Files: conversation/src/http/routes/computer-files.ts (live or snapshot, PUT, reveal, watch), http/app.ts (declare), snapshot/files.ts (reveal option, provenance fields, modified_at), domain/file-audit.ts (new), lambdas/front-door-composition.ts (wire the store methods and the clock/sleep), http/errors or the route file for the codes of 6.3. Steps: features-support/steps/computer-file-live.steps.ts. Scenarios: LF-1 to LF-14, LF-17 to LF-20, LF-22 to LF-27. Existing scenarios that change: computer_snapshot_index.feature (responses gain stale, fallback_reason, modified_at, source stays snapshot). Acceptance: those scenarios green; on development, curl shows If-Match reaches the handler and ETag returns.

Revision 2 adds the overlay integration: http/routes/computer-files.ts routes the write per 7.3 step 4 (customer, live, owner_too_old, stopping, starting, overlay), merges the overlay into every snapshot answer (7.2 step 3, L43), adds overlay, mine_sha256, variant, source: "overlay"; snapshot/files.ts accepts the overlay for list, stat, content and reveal and answers an empty /workspace plus the overlay when nothing was published. Scenarios: LF-1 to LF-14, LF-17 to LF-20, LF-22 to LF-27, LF-47 to LF-52, LF-54, LF-57 (member side), LF-58.

A2 as built (features/computer_file_live_member.feature, steps in features-support/steps/computer-file-live.steps.ts, a FakeLiveDisk in features-support/fakes/). Where the code differs from the text above:

• The routes are http/routes/computer-files.ts; the decisions are in domain/member-files.ts (routingContextOf, readThroughOwner, performMemberChange, refusalOfOwnerError), domain/file-audit.ts (memberAuditRecordOf, StoreOverlayAuditSink), domain/file-rate-limit.ts and domain/member-file-refusal.ts. Part A4 adds routes that build a MemberFileChange (the audit intent, the owner request and the overlay request of one change) and call performMemberChange; the live path, the audit, the wait, the abandon rule and the overlay path are not repeated.
• The wait is awaitLiveFileOutcome in domain/live-files.ts, with the sleep behind a FileWaitPort (createApp({ fileWait })), so no scenario waits for real time.
• LIVE_FILE_ERROR_STATUS (section 6.3) lives in host-protocol/src/live-files.ts; SnapshotFileError and EditOverlayRefusal take their statuses from it.
• An organization is a customer-account organization when its awsAccountId is set and is not the deployment account (createApp({ deploymentAwsAccountId })).
• A .git path is refused and audited by the Front Door on the live path (7.3 step 3); on the overlay path the write algebra refuses it and writes the same record.
• A reveal writes its audit record just before it queues the request (after the pickup and busy checks, which are not audited), and with the source it is answered from: live, overlay for a pending edit, snapshot otherwise. A live reveal that falls back is finished ok by the Front Door.
• stat answers tree_sha256: null for a directory in this part; the tree hash as an ETag arrives with the delete and rename routes of part A4.
• The production composition now passes editOverlay (the S3 overlay store, the S3 snapshot store, StoreOverlayAuditSink over the messaging store); before it the overlay owner routes answered 503.
• The ETag of variant=mine is the hash of the person's text.

A4 as built (features/computer_file_live_operations.feature, steps in features-support/steps/computer-file-operations.steps.ts; FakeLiveDisk learned stat with a tree hash, delete, move and mkdir with the helper's precondition rules). Where the code differs from the text above:

• The routes are http/routes/computer-file-operations.ts (DELETE /files, POST /files/move, POST /files/directories); GET /files/overlay stays with part A3. Each builds a MemberFileChange and calls performMemberChange.
• The ETag of stat is the effective hash: the tree hash of a folder (also in entry.tree_sha256), the link hash of a link (also in entry.sha256), the content hash of a file. A live stat asks the owner with hash: true: the owner hashes a regular file of at most 8 MiB, so a running computer gives a file the same ETag on stat as on content; a larger file answers 413 file_too_large on stat (the panel words it as for an over-limit file). A folder over 5000 descendants answers 413 too_many_entries on stat.
• A person's If-Match does not say whether it is a content hash, a link hash or a tree hash, and it does not need to: the live request carries it as the one if_match precondition and the owner's helper compares it with the effective hash of what is really at the path. A delete or a rename on the live path is therefore one round trip to the owner. A path that is not there is the owner's 404 not_found, and the attempt is audited as failed with that code like any other answer. Because the Front Door does not know the kind on that path, the audit record of a live delete without recursive, and of a live rename, holds the hash seen in sha256_before whatever it is the hash of; a recursive delete, which is always a folder, records tree_sha256_before.
• recursive=true needs the organization owner role whether or not the folder has children: one rule on both paths, checked before anything is queued or written. The refusal is audited as refused (7.8.8), not merely logged (7.8.1).
• On the live path the Front Door cannot know that a mkdir finds the folder already there, so that idempotent call is audited (the overlay path does not audit it).

C. Container: helper and the supervisor's file runner (needs F0)

(Revision 3 adds to this part: the helper operations of 8.1 (mkdir, unlink, rmtree, rename, stat with hash), the runner's mapping of request kinds delete, move, mkdir, and the tree hash and symlink hash in host-protocol/src/live-file-rules.ts shared with the Front Door. Scenarios: LF-74.)

Files: conversation/src/pi/owner-file-helper.ts (section 8), conversation/src/pi/unprivileged-execution-env.ts (Pi write through the same operation), conversation/src/pi/shell-environment.ts (new, extracted), computer/host/src/live-file-operations.ts (new), computer/host/src/live-file-helper-launcher.ts (new), computer/host/src/supervisor.ts, supervisor-ports.ts, supervisor-main.ts, protocol-client.ts, unprivileged-process-sweeper.ts only if the mutex needs a hook, owner-main.ts (a live-file-probe subcommand beside file-probe), host-protocol/src/supervisor.ts (OWNER_PROTOCOL_VERSION = 2, one line, in this part), computer/test_owner_container.sh (run live-file-probe for list, read, write and the .git refusal as the shell user), conversation/test/computer-image-structure.test.ts (the supervisor bundle does not gain node:fs use on request paths, Pi or the starter). Tests: test/owner-file-helper.test.ts (extend), test/live-file-operations.test.ts. Steps: features-support/steps/live-file-supervisor.steps.ts, a fake launcher and fake plane in features-support/fakes/. Scenarios: LF-12 (helper), LF-16, LF-32 to LF-39. Acceptance: those green; computer_owner_file_isolation.feature and computer_owner_supervisor.feature green; the image builds; test_owner_container.sh passes (it needs Docker; an owner of the image runs it, Kanbus chatticus-6c66c5 tracks the local image build).

C2. Container: the overlay at hydrate (needs F0 and C; the control plane side is faked)

(Revision 3: the applier implements the order and the outcome table of 7.8.5 for all four operations, with the detection of "already applied" through the helper's stat (tree hash) and read (hash). Scenarios: LF-73.)

Files: computer/host/src/overlay-applier.ts (new, 9.4), host-disk-lifecycle.ts, supervisor.ts (applied set, early publish check, capture-and-clear, retry), supervisor-ports.ts, protocol-client.ts (sealOverlay, postOverlayApplied), supervisor-main.ts (wire the applier and the launcher), computer/test_owner_container.sh (an overlay entry applied by a real container), conversation/test/computer-image-structure.test.ts (the bundle still imports no Pi). Tests: test/overlay-applier.test.ts with a fake launcher, plane and S3. Steps: features-support/steps/overlay-supervisor.steps.ts, fakes in features-support/fakes/. Scenarios: LF-57 (supervisor), LF-60 to LF-62. Acceptance: those green; computer_owner_supervisor.feature unchanged and green; the image builds.

W. Web (needs F0 for the shapes; develops against fixtures; integrates after A2)

Files: section 10. New web/lib/computer-files-edit.ts; changes to computer-files.ts, computer-files-api.ts, touched-files.ts, ComputerFilesPanel.tsx, ComputerFilesView.tsx, the fixtures; vitest beside each; the @web steps in the web harness (features-support/web-harness-runner.ts, steps/web-*.steps.ts), which has no file-panel steps today and must learn a fake running computer. Scenarios: LF-40 to LF-45. Acceptance: those green, npm test in web/ green, a manual pass at 375 pixels width, and docs/BRAND_GUIDELINES.md followed.

Revision 3 adds: delete, rename and new folder controls (any member; the recursive delete of a non-empty folder only for the owner role, behind a confirmation that names the folder and the count), pending-change marks and a Pending changes list with discard, tree-hash ETag of a folder from stat, wording for path_busy, directory_not_empty, owner_role_required, invalid_move, too_many_entries. Scenarios: LF-75.

Revision 2 adds: edit while the computer is off (source: "overlay"), the Edited, waiting for the computer mark, the overlay conflict banner, the retry on computer_starting and computer_stopping, the new error wording, backed_up messages (section 10). Scenarios: LF-40 to LF-45 and LF-63.

E. End to end and live proof (needs A2, A4 and C2)

The @end-to-end scenarios (LF-46, LF-64, LF-76) in one steps file, the live proof (section 17), and the milestone sub-agent for Kanbus and README.

E as built (features/computer_file_live_end_to_end.feature, steps in features-support/steps/live-files-end-to-end.steps.ts with features-support/live-files-end-to-end-support.ts; LF-59 is features/computer_file_overlay_authority.feature). Where the code differs from the text above:

• The scenarios run the production routes with the real OwnerSupervisor loop (the long-lived harness of owner-long-lived.steps.ts, now parameterised by a wiring), the real HostDiskLifecycle over the scenario's bucket, the real SealingOverlayApplier and the real file helper run in the test process on a real directory. A bot's turn works in the same directory, so one disk is seen by the member, the helper and the bot. The FakeLiveDisk is not used here: it answers owner requests in memory and the bot's tools need a real workspace. Time, the child process of a turn, the model, the credential broker and the wait of the Front Door (ScenarioFileWait) are faked.
• Time moves only by waking the supervisor's sleepers; work the supervisor does in real time (restore, publish, helper) is counted as in flight and finishes before time moves on. Each supervisor the scenario starts gets a fresh live disk, as each task of the computer does.
• "A task that crashes" is a supervisor that is never woken again. The next owner can be started only after the heartbeat has lapsed (30 seconds) and the start lease of the dead task has run out (HOST_START_LEASE_SECONDS, 60), so the crash scenario lets 61 seconds go by, not 31.
• LF-64 (empty after the publish): the scenario also lets the supervisor idle until it stops (reason idle) and then asserts the overlay is empty and not sealed, which is the state 17 step 6a promises "after the stop".
• LF-59 second scenario: the first write of the index is create-only (If-None-Match: *); the If-Match of the entity tag that was read applies to every later write, so the scenario makes two edits and checks the chain of tags against moto's conditional writes.
• The scenario that lists the workspace for the bot runs ls with cwd /workspace instead of ls /workspace, because the test shell has no /workspace directory.

Order and dependencies

1. This contract (with the feature draft and the design document edits) merges.
2. F0 merges. B is independent and can merge at any time before the server parts deploy.
3. After F0: A1, A3, C and W start in parallel. A2 needs A1 and A3. A4 needs A2 and A3. C2 needs C.
4. E needs A2, A4 and C2 (and so B, A1, A3, C).

Deploy order (development; no compatibility path)

1. B (the Front Door may write the overlay; the supervisor role is denied; the 30 day expiry of non-current versions) before anything writes an overlay object.
2. A1, A3, A2 and A4: the routes exist; every running owner is protocol 1, so file requests are answered from the snapshot with owner_too_old, edits go to the overlay when the computer is off, and are refused 409 owner_too_old while such an owner runs.
3. C and C2 (one image): the next owner started is protocol 2, seals, applies, serves file requests. An overlay entry written before it exists is applied by it.
4. W when A2 is deployed.
5. The live proof (section 17).

16. What changes in existing tests and files

conversation/test/owner-supervisor-protocol-schema.test.ts (poll response, veto and error enums, constants), conversation/test/owner-supervisor-domain.test.ts (approveOwnerStop signature, poll with file requests), conversation/test/route-audience.test.ts (the new routes), conversation/test/dynamo-messaging-store.contract.test.ts, features/computer_snapshot_index.feature and computer-snapshot-files.steps.ts (new response fields), features/owner_role_policy.feature and computer_owner_policy_coverage.feature (the two key families are denied to both roles), features/computer_owner_file_isolation.feature (stays green; the Pi write is atomic), conversation/test/owner-file-helper.test.ts, conversation/test/computer-image-structure.test.ts, computer/test_owner_container.sh, web/lib/computer-files*.test.ts, web/lib/touched-files.test.ts, web/lib/computer-files-fixtures.ts. Revision 3 adds: conversation/test/overlay-merge.test.ts (four operations), owner-file-helper.test.ts (8.1), computer-image-structure.test.ts (no change in imports), infra/test (the lifecycle rule), web/lib/computer-files*.test.ts (new controls and pending list). Revision 2 adds: features/owner_role_policy.feature and computer_owner_policy_coverage.feature (overlay rows, the deny), features-support/iam-policy-evaluator.ts (Deny), infra/test/computer-owner-stack.test.ts, conversation/test/snapshot-files*.test.ts and features/computer_snapshot_index.feature (the overlay merged into snapshot answers, the empty-snapshot case), computer/host/src/host-disk-lifecycle.ts tests, computer/test_owner_container.sh. The list is the author's reading of the code; the implementer finds the rest by running the gates.

17. Live proof (development)

1. Send a message that makes a bot create two files. While the turn is done and the computer is idle, open the Files panel: the source line reads Live from the computer; the new files are listed and openable before snapshot_published appears in the log. The log shows file_operation lines with path_hash and no paths.
2. Edit a file in the panel and save: Saved on the computer; ask the bot to read it back and it answers with the new text; the owner log shows file_operation kind=write outcome=ok, then snapshot_published about 30 seconds later.
3. Edit the same file from both sides at once (ask the bot to rewrite it while the panel is in edit mode): one edit stands and the panel shows the conflict banner with the bot's version.
4. In the table, find the audit records of step 2 and 3 ({tenant}#computer#audit): user id, path, hashes, outcome, no content. Reveal a .env file: a reveal record exists.
5. Close the panel and watch the poll pace return from 1 second to the idle tier within a minute (owner_polling interval_ms). Leave the computer for 15 minutes: owner_stopping reason=idle, with the last edit in the snapshot.
6. With the computer off, open the panel: Computer is off. Showing the copy saved ..., with the editor. Edit a file and save: Saved. Your change will be applied when the computer starts. In aws ecs list-tasks no task appeared; the computer record is unchanged; overlay/index.json and one blob exist under the computer's prefix; the audit has a record with source overlay. 6a. Ask the bot to read that file. The log shows owner_started, workspace_hydrated, overlay_sealed, overlay_applied before owner_dispatch_received; the bot answers with the edited text. About 5 seconds after the supervisor is idle, snapshot_published and overlay_cleared remaining=0; overlay/index.json is empty and unsealed after the stop. 6b. Edit a second file while the computer is off, start it, and aws ecs stop-task it right after overlay_applied and before snapshot_published: the panel still shows the edit (snapshot plus overlay), and the next owner applies it. 6c. Make the snapshot move under an edit (publish a different content for the same file from another path, for example by a bot turn on a copy) and see the conflict banner; resolve it with Use theirs. 6d. With the computer off: delete a file, rename a file, rename a folder that is not empty, create a folder, as a member; try to delete a non-empty folder as a member (403) and as the owner role (accepted, with the confirmation). Start the computer by sending a message: the log shows overlay_applied with the operations in the order mkdir, move, put, delete; the bot lists the workspace and sees the deleted, renamed and created paths; after the publish the overlay is empty. 6e. Rename a file onto an existing name (409), delete a file after another path changed it (409), and see a conflict for a rename whose source the snapshot changed.
7. Check on the CloudFront path: If-Match arrives, ETag returns, the PUT body of 256 KiB passes.
8. Prove S3 conditional writes on the real bucket (the If-Match and If-None-Match of the overlay index) and that the supervisor credentials are denied a PutObject to overlay/ (aws s3api put-object with them). Measure on a running 512 MiB owner: memory with two helpers reading 8 MiB files during a quiet publish (risk R1).

18. Assumptions and risks

Assumptions (marked where they appear): CloudFront forwards If-Match and returns ETag unchanged on /api* (6.2); a Node helper costs 40 to 60 MiB (12.5); SHA-256 of 8 MiB on 0.25 vCPU takes well under a second; the 342 KB worst-case item and result body fit the Lambda and table limits (L20); fsync on the task's ephemeral disk is cheap; the membership cache bound of 30 seconds; DynamoDB TransactWriteItems on the computer record and a request item is available with the same client the store already uses (dynamo-messaging-store.ts imports TransactWriteItemsCommand).

19. Cost

Prices (US East; ASSUMPTION: not re-verified in this session): S3 PUT 0.005 USD per 1000, GET 0.0004 USD per 1000, storage 0.023 USD per GB-month, DynamoDB on-demand write 0.625 USD per million write units, Lambda ARM 0.0000133 USD per GB-second.