@p4code/cli 0.1.7 → 0.1.9

package/dist/bin.mjs

@@ -233,7 +233,7 @@ const make$73 = () => {
 const layer$69 = Layer.sync(NetService, make$73);
 //#endregion
 //#region package.json
-var version = "0.1.7";
+var version = "0.1.9";
 //#endregion
 //#region src/config.ts
 /**
@@ -7012,175 +7012,6 @@ const GitActionProgressEvent = Schema$1.Union([
 	GitActionFailedEvent
 ]);
 //#endregion
-//#region ../../packages/contracts/src/p4ProjectFile.ts
-/** File name of the checked-in P4 project file, resolved at the workspace root. */
-const P4_PROJECT_FILE_NAME = "p4.json";
-/** Public URL of the published JSON Schema for {@link P4ProjectFile}. */
-const P4_PROJECT_FILE_SCHEMA_URL = "https://p4.codes/schema/p4.json";
-const P4_PROJECT_FILE_PATH_MAX_LENGTH = 512;
-const P4_PROJECT_FILE_MAX_SCRIPTS = 50;
-const trimmedNonEmpty = (annotations, maxLength) => {
-	const annotated = Schema$1.String.annotate(annotations);
-	const encoded = maxLength === void 0 ? annotated.check(Schema$1.isNonEmpty()) : annotated.check(Schema$1.isNonEmpty(), Schema$1.isMaxLength(maxLength));
-	return encoded.pipe(Schema$1.decodeTo(encoded, SchemaTransformation.trim()));
-};
-const P4ProjectFileScript = Schema$1.Struct({
-	name: trimmedNonEmpty({ description: "Display name for the script, shown in the P4Code scripts menu." }),
-	command: trimmedNonEmpty({ description: "Shell command executed in a P4Code terminal at the project root." }),
-	icon: Schema$1.optionalKey(ProjectScriptIcon.annotate({ description: "Icon shown next to the script in the scripts menu. Defaults to \"play\"." })),
-	runOnWorktreeCreate: Schema$1.optionalKey(Schema$1.Boolean.annotate({ description: "When true, the script runs automatically after a worktree is created for a new thread." })),
-	previewUrl: Schema$1.optionalKey(trimmedNonEmpty({ description: "URL opened in the in-app browser preview when this script runs. Only honored on the desktop build." })),
-	autoOpenPreview: Schema$1.optionalKey(Schema$1.Boolean.annotate({ description: "When true, automatically open the preview panel at `previewUrl` the moment the script starts." }))
-}).annotate({ description: "A project script that team members can import into P4Code." });
-const P4ProjectFile = Schema$1.Struct({
-	$schema: Schema$1.optionalKey(Schema$1.String.annotate({ description: `URL of the JSON Schema for this file, typically "${P4_PROJECT_FILE_SCHEMA_URL}".` })),
-	iconPath: Schema$1.optionalKey(trimmedNonEmpty({ description: "Workspace-relative path to the project icon (e.g. \"assets/logo.svg\"). Checked before P4Code's built-in icon locations." }, P4_PROJECT_FILE_PATH_MAX_LENGTH)),
-	scripts: Schema$1.optionalKey(Schema$1.Array(P4ProjectFileScript).annotate({ description: "Project scripts shared with everyone who opens this repository in P4Code." }).check(Schema$1.isMaxLength(P4_PROJECT_FILE_MAX_SCRIPTS)))
-}).annotate({
-	title: "P4 project file",
-	description: "Checked-in project configuration for P4Code (p4.json at the repository root). See https://p4.codes for documentation."
-});
-//#endregion
-//#region ../../packages/contracts/src/project.ts
-const PROJECT_SEARCH_ENTRIES_MAX_LIMIT = 200;
-const PROJECT_WRITE_FILE_PATH_MAX_LENGTH = 512;
-const PROJECT_READ_FILE_PATH_MAX_LENGTH = 512;
-const ProjectSearchEntriesInput = Schema$1.Struct({
-	cwd: TrimmedNonEmptyString,
-	query: TrimmedNonEmptyString.check(Schema$1.isMaxLength(256)),
-	limit: PositiveInt.check(Schema$1.isLessThanOrEqualTo(PROJECT_SEARCH_ENTRIES_MAX_LIMIT))
-});
-const ProjectEntryKind = Schema$1.Literals(["file", "directory"]);
-const ProjectEntry = Schema$1.Struct({
-	path: TrimmedNonEmptyString,
-	kind: ProjectEntryKind
-});
-const ProjectSearchEntriesResult = Schema$1.Struct({
-	entries: Schema$1.Array(ProjectEntry),
-	truncated: Schema$1.Boolean
-});
-const ProjectListEntriesInput = Schema$1.Struct({ cwd: TrimmedNonEmptyString });
-const ProjectListEntriesResult = Schema$1.Struct({
-	entries: Schema$1.Array(ProjectEntry),
-	truncated: Schema$1.Boolean
-});
-const ProjectEntriesFailure = Schema$1.Literals([
-	"workspace_root_not_found",
-	"workspace_root_create_failed",
-	"workspace_root_stat_failed",
-	"workspace_root_not_directory",
-	"search_index_create_failed",
-	"search_index_scan_timed_out",
-	"search_index_search_failed"
-]);
-function decodedProjectErrorMessage(props) {
-	if (!("message" in props)) return void 0;
-	return typeof props.message === "string" ? props.message : void 0;
-}
-var ProjectSearchEntriesError = class extends Schema$1.TaggedErrorClass()("ProjectSearchEntriesError", {
-	cwd: Schema$1.optional(TrimmedNonEmptyString),
-	queryLength: Schema$1.optional(NonNegativeInt),
-	limit: Schema$1.optional(PositiveInt),
-	failure: Schema$1.optional(ProjectEntriesFailure),
-	normalizedCwd: Schema$1.optional(TrimmedNonEmptyString),
-	timeout: Schema$1.optional(TrimmedNonEmptyString),
-	detail: Schema$1.optional(TrimmedNonEmptyString),
-	message: TrimmedNonEmptyString,
-	cause: Schema$1.optional(Schema$1.Defect())
-}) {
-	constructor(props) {
-		super({
-			...props,
-			message: decodedProjectErrorMessage(props) ?? `Failed to search workspace entries in '${props.cwd}'.`
-		});
-	}
-};
-var ProjectListEntriesError = class extends Schema$1.TaggedErrorClass()("ProjectListEntriesError", {
-	cwd: Schema$1.optional(TrimmedNonEmptyString),
-	failure: Schema$1.optional(ProjectEntriesFailure),
-	normalizedCwd: Schema$1.optional(TrimmedNonEmptyString),
-	timeout: Schema$1.optional(TrimmedNonEmptyString),
-	detail: Schema$1.optional(TrimmedNonEmptyString),
-	message: TrimmedNonEmptyString,
-	cause: Schema$1.optional(Schema$1.Defect())
-}) {
-	constructor(props) {
-		super({
-			...props,
-			message: decodedProjectErrorMessage(props) ?? `Failed to list workspace entries in '${props.cwd}'.`
-		});
-	}
-};
-const ProjectReadFileInput = Schema$1.Struct({
-	cwd: TrimmedNonEmptyString,
-	relativePath: TrimmedNonEmptyString.check(Schema$1.isMaxLength(PROJECT_READ_FILE_PATH_MAX_LENGTH))
-});
-const ProjectReadFileResult = Schema$1.Struct({
-	relativePath: TrimmedNonEmptyString,
-	contents: Schema$1.String,
-	byteLength: NonNegativeInt,
-	truncated: Schema$1.Boolean
-});
-const ProjectFileFailure = Schema$1.Literals([
-	"workspace_path_outside_root",
-	"resolved_path_outside_root",
-	"path_not_file",
-	"binary_file",
-	"operation_failed"
-]);
-const ProjectFileOperation = Schema$1.Literals([
-	"realpath-workspace-root",
-	"realpath-target",
-	"open",
-	"stat",
-	"read",
-	"close",
-	"make-directory",
-	"write-file"
-]);
-var ProjectReadFileError = class extends Schema$1.TaggedErrorClass()("ProjectReadFileError", {
-	cwd: Schema$1.optional(TrimmedNonEmptyString),
-	relativePath: Schema$1.optional(TrimmedNonEmptyString),
-	failure: Schema$1.optional(ProjectFileFailure),
-	resolvedPath: Schema$1.optional(TrimmedNonEmptyString),
-	resolvedWorkspaceRoot: Schema$1.optional(TrimmedNonEmptyString),
-	operation: Schema$1.optional(ProjectFileOperation),
-	operationPath: Schema$1.optional(TrimmedNonEmptyString),
-	message: TrimmedNonEmptyString,
-	cause: Schema$1.optional(Schema$1.Defect())
-}) {
-	constructor(props) {
-		super({
-			...props,
-			message: decodedProjectErrorMessage(props) ?? `Failed to read workspace file '${props.relativePath}' in '${props.cwd}'.`
-		});
-	}
-};
-const ProjectWriteFileInput = Schema$1.Struct({
-	cwd: TrimmedNonEmptyString,
-	relativePath: TrimmedNonEmptyString.check(Schema$1.isMaxLength(PROJECT_WRITE_FILE_PATH_MAX_LENGTH)),
-	contents: Schema$1.String
-});
-const ProjectWriteFileResult = Schema$1.Struct({ relativePath: TrimmedNonEmptyString });
-var ProjectWriteFileError = class extends Schema$1.TaggedErrorClass()("ProjectWriteFileError", {
-	cwd: Schema$1.optional(TrimmedNonEmptyString),
-	relativePath: Schema$1.optional(TrimmedNonEmptyString),
-	failure: Schema$1.optional(ProjectFileFailure),
-	resolvedPath: Schema$1.optional(TrimmedNonEmptyString),
-	resolvedWorkspaceRoot: Schema$1.optional(TrimmedNonEmptyString),
-	operation: Schema$1.optional(ProjectFileOperation),
-	operationPath: Schema$1.optional(TrimmedNonEmptyString),
-	message: TrimmedNonEmptyString,
-	cause: Schema$1.optional(Schema$1.Defect())
-}) {
-	constructor(props) {
-		super({
-			...props,
-			message: decodedProjectErrorMessage(props) ?? `Failed to write workspace file '${props.relativePath}' in '${props.cwd}'.`
-		});
-	}
-};
-//#endregion
 //#region ../../packages/contracts/src/task.ts
 const TASK_TITLE_MAX_LENGTH = 512;
 const TASK_LABEL_MAX_LENGTH = 64;
@@ -7205,6 +7036,19 @@ const TaskPriority = Schema$1.Literals([
 	"high",
 	"urgent"
 ]);
+/**
+* A per-prefix sequence prefix, e.g. `T` or `P4`. Declared by a project in its
+* `p4.json` (`taskPrefix`); always stored and compared uppercase.
+*/
+const TASK_READABLE_ID_PREFIX_PATTERN = /^[A-Za-z][A-Za-z0-9]{0,9}$/;
+/**
+* The shape of a readable task id: prefix, dash, 1-based sequence number.
+* Deliberately disjoint from the UUID `taskId`, which is what lets a lookup
+* accept either and tell them apart by shape alone.
+*/
+const TASK_READABLE_ID_PATTERN = /^[A-Za-z][A-Za-z0-9]{0,9}-[1-9][0-9]*$/;
+/** Whether a task reference is a readable id (`P4-12`) rather than a UUID. */
+const isReadableTaskId = (reference) => TASK_READABLE_ID_PATTERN.test(reference);
 const TaskLabel = TrimmedNonEmptyString.check(Schema$1.isMaxLength(TASK_LABEL_MAX_LENGTH));
 /**
 * Agent-facing field descriptions. These ride on the *encoded* side because
@@ -7232,11 +7076,37 @@ const AssigneeField = TrimmedNonEmptyString.check(Schema$1.isMaxLength(TASK_ASSI
 * no remote, where there is nothing stable to key on.
 */
 const RepositoryKeyField = TrimmedNonEmptyString.pipe(Schema$1.annotateEncoded({ description: "Canonical repository key (normalized git remote, e.g. github.com/owner/repo). Portable across machines, unlike projectId." }));
+/**
+* Manual board position within a column, as a lexicographic fractional key.
+*
+* Compared as a plain string: smaller sorts higher. Keys are minted by the
+* board between the neighbours of a drop, so moving one card writes one row
+* rather than renumbering the column. `null` means the task has never been
+* placed by hand and falls back to the priority/recency order.
+*/
+const OrderKeyField = TrimmedNonEmptyString.pipe(Schema$1.annotateEncoded({ description: "Manual board position key. Lexicographic: smaller sorts higher in the column. Null means no manual position." }));
 const LabelsField = Schema$1.Array(TaskLabel).check(Schema$1.isMaxLength(TASK_LABELS_MAX_COUNT)).pipe(Schema$1.annotateEncoded({ description: "Free-form tags used to group and filter tasks." }));
-const TaskIdField = TaskId.pipe(Schema$1.annotateEncoded({ description: "Id of the task to act on." }));
+const TaskIdField = TaskId.pipe(Schema$1.annotateEncoded({ description: "Id of the task to act on - the UUID or the readable id (e.g. P4-12)." }));
 const Task = Schema$1.Struct({
 	taskId: TaskId,
 	/**
+	* The human-readable id, e.g. `T-1` or `P4-12`: a per-prefix sequence
+	* allocated by the store that owns the row, never reused, with gaps where
+	* tasks were deleted. Nullable only for version skew - a row read from a
+	* store that has not run the backfill migration decodes to `null` rather
+	* than failing the whole board.
+	*/
+	readableId: Schema$1.NullOr(TrimmedNonEmptyString).pipe(Schema$1.withDecodingDefault(Effect.succeed(null))),
+	/**
+	* Manual board position: a lexicographic fractional key, compared as a plain
+	* string, smaller first. Written only when a card is dragged to a position;
+	* `null` means "never placed by hand" and the board falls back to its
+	* priority/recency order. Nullable-with-default for the same version-skew
+	* reason as `readableId`: a row from a store without the migration decodes to
+	* `null` rather than failing the whole board.
+	*/
+	orderKey: Schema$1.NullOr(TrimmedNonEmptyString).pipe(Schema$1.withDecodingDefault(Effect.succeed(null))),
+	/**
 	* The project this task belongs to, or `null` for a task that is not scoped
 	* to one. This references the existing workspace project registry rather than
 	* a task-board-private notion of a project.
@@ -7277,6 +7147,27 @@ const TaskCreateInput = Schema$1.Struct({
 	labels: Schema$1.optional(LabelsField)
 });
 /**
+* What an environment server sends the hub to file a task.
+*
+* Extends the public create input with the readable-id prefix, because the two
+* halves of the answer live on different machines: the prefix comes from the
+* project's checked-in `p4.json`, which only the submitting server can read,
+* while the sequence number must be allocated by the hub, which is the only
+* party that sees every machine's writes. Deliberately not part of
+* `TaskCreateInput` itself so an agent filing over MCP cannot pick a prefix -
+* the prefix belongs to the project, not to the caller.
+*/
+const HubTaskCreateInput = Schema$1.Struct({
+	...TaskCreateInput.fields,
+	readableIdPrefix: Schema$1.optional(TrimmedNonEmptyString),
+	/**
+	* Carried on the hub's create route (but not the public one) so a server
+	* mirroring an already-placed row to the hub does not lose its position.
+	* An agent filing a new task has no business picking a slot.
+	*/
+	orderKey: Schema$1.optional(OrderKeyField)
+});
+/**
 * Every field is optional and an omitted field is left untouched. The nullable
 * fields accept an explicit `null` to clear them, which is why they are
 * `NullOr` inside `optional` rather than merely optional.
@@ -7291,7 +7182,8 @@ const TaskUpdateInput = Schema$1.Struct({
 	status: Schema$1.optional(StatusField),
 	priority: Schema$1.optional(PriorityField),
 	assignee: Schema$1.optional(Schema$1.NullOr(AssigneeField)),
-	labels: Schema$1.optional(LabelsField)
+	labels: Schema$1.optional(LabelsField),
+	orderKey: Schema$1.optional(Schema$1.NullOr(OrderKeyField))
 });
 /**
 * A task an agent has drafted but has not filed.
@@ -7480,6 +7372,176 @@ const TaskToolError = Schema$1.Union([
 	TaskStoreError
 ]);
 //#endregion
+//#region ../../packages/contracts/src/p4ProjectFile.ts
+/** File name of the checked-in P4 project file, resolved at the workspace root. */
+const P4_PROJECT_FILE_NAME = "p4.json";
+/** Public URL of the published JSON Schema for {@link P4ProjectFile}. */
+const P4_PROJECT_FILE_SCHEMA_URL = "https://p4.codes/schema/p4.json";
+const P4_PROJECT_FILE_PATH_MAX_LENGTH = 512;
+const P4_PROJECT_FILE_MAX_SCRIPTS = 50;
+const trimmedNonEmpty = (annotations, maxLength) => {
+	const annotated = Schema$1.String.annotate(annotations);
+	const encoded = maxLength === void 0 ? annotated.check(Schema$1.isNonEmpty()) : annotated.check(Schema$1.isNonEmpty(), Schema$1.isMaxLength(maxLength));
+	return encoded.pipe(Schema$1.decodeTo(encoded, SchemaTransformation.trim()));
+};
+const P4ProjectFileScript = Schema$1.Struct({
+	name: trimmedNonEmpty({ description: "Display name for the script, shown in the P4Code scripts menu." }),
+	command: trimmedNonEmpty({ description: "Shell command executed in a P4Code terminal at the project root." }),
+	icon: Schema$1.optionalKey(ProjectScriptIcon.annotate({ description: "Icon shown next to the script in the scripts menu. Defaults to \"play\"." })),
+	runOnWorktreeCreate: Schema$1.optionalKey(Schema$1.Boolean.annotate({ description: "When true, the script runs automatically after a worktree is created for a new thread." })),
+	previewUrl: Schema$1.optionalKey(trimmedNonEmpty({ description: "URL opened in the in-app browser preview when this script runs. Only honored on the desktop build." })),
+	autoOpenPreview: Schema$1.optionalKey(Schema$1.Boolean.annotate({ description: "When true, automatically open the preview panel at `previewUrl` the moment the script starts." }))
+}).annotate({ description: "A project script that team members can import into P4Code." });
+const P4ProjectFile = Schema$1.Struct({
+	$schema: Schema$1.optionalKey(Schema$1.String.annotate({ description: `URL of the JSON Schema for this file, typically "${P4_PROJECT_FILE_SCHEMA_URL}".` })),
+	iconPath: Schema$1.optionalKey(trimmedNonEmpty({ description: "Workspace-relative path to the project icon (e.g. \"assets/logo.svg\"). Checked before P4Code's built-in icon locations." }, P4_PROJECT_FILE_PATH_MAX_LENGTH)),
+	scripts: Schema$1.optionalKey(Schema$1.Array(P4ProjectFileScript).annotate({ description: "Project scripts shared with everyone who opens this repository in P4Code." }).check(Schema$1.isMaxLength(P4_PROJECT_FILE_MAX_SCRIPTS))),
+	taskPrefix: Schema$1.optionalKey(trimmedNonEmpty({ description: "Prefix for this project's readable task ids on the task board (e.g. \"P4\" numbers tasks P4-1, P4-2, ...). Letters and digits, starting with a letter, at most 10 characters; compared case-insensitively. Tasks without a project use \"T\"." }).check(Schema$1.isPattern(TASK_READABLE_ID_PREFIX_PATTERN)))
+}).annotate({
+	title: "P4 project file",
+	description: "Checked-in project configuration for P4Code (p4.json at the repository root). See https://p4.codes for documentation."
+});
+//#endregion
+//#region ../../packages/contracts/src/project.ts
+const PROJECT_SEARCH_ENTRIES_MAX_LIMIT = 200;
+const PROJECT_WRITE_FILE_PATH_MAX_LENGTH = 512;
+const PROJECT_READ_FILE_PATH_MAX_LENGTH = 512;
+const ProjectSearchEntriesInput = Schema$1.Struct({
+	cwd: TrimmedNonEmptyString,
+	query: TrimmedNonEmptyString.check(Schema$1.isMaxLength(256)),
+	limit: PositiveInt.check(Schema$1.isLessThanOrEqualTo(PROJECT_SEARCH_ENTRIES_MAX_LIMIT))
+});
+const ProjectEntryKind = Schema$1.Literals(["file", "directory"]);
+const ProjectEntry = Schema$1.Struct({
+	path: TrimmedNonEmptyString,
+	kind: ProjectEntryKind
+});
+const ProjectSearchEntriesResult = Schema$1.Struct({
+	entries: Schema$1.Array(ProjectEntry),
+	truncated: Schema$1.Boolean
+});
+const ProjectListEntriesInput = Schema$1.Struct({ cwd: TrimmedNonEmptyString });
+const ProjectListEntriesResult = Schema$1.Struct({
+	entries: Schema$1.Array(ProjectEntry),
+	truncated: Schema$1.Boolean
+});
+const ProjectEntriesFailure = Schema$1.Literals([
+	"workspace_root_not_found",
+	"workspace_root_create_failed",
+	"workspace_root_stat_failed",
+	"workspace_root_not_directory",
+	"search_index_create_failed",
+	"search_index_scan_timed_out",
+	"search_index_search_failed"
+]);
+function decodedProjectErrorMessage(props) {
+	if (!("message" in props)) return void 0;
+	return typeof props.message === "string" ? props.message : void 0;
+}
+var ProjectSearchEntriesError = class extends Schema$1.TaggedErrorClass()("ProjectSearchEntriesError", {
+	cwd: Schema$1.optional(TrimmedNonEmptyString),
+	queryLength: Schema$1.optional(NonNegativeInt),
+	limit: Schema$1.optional(PositiveInt),
+	failure: Schema$1.optional(ProjectEntriesFailure),
+	normalizedCwd: Schema$1.optional(TrimmedNonEmptyString),
+	timeout: Schema$1.optional(TrimmedNonEmptyString),
+	detail: Schema$1.optional(TrimmedNonEmptyString),
+	message: TrimmedNonEmptyString,
+	cause: Schema$1.optional(Schema$1.Defect())
+}) {
+	constructor(props) {
+		super({
+			...props,
+			message: decodedProjectErrorMessage(props) ?? `Failed to search workspace entries in '${props.cwd}'.`
+		});
+	}
+};
+var ProjectListEntriesError = class extends Schema$1.TaggedErrorClass()("ProjectListEntriesError", {
+	cwd: Schema$1.optional(TrimmedNonEmptyString),
+	failure: Schema$1.optional(ProjectEntriesFailure),
+	normalizedCwd: Schema$1.optional(TrimmedNonEmptyString),
+	timeout: Schema$1.optional(TrimmedNonEmptyString),
+	detail: Schema$1.optional(TrimmedNonEmptyString),
+	message: TrimmedNonEmptyString,
+	cause: Schema$1.optional(Schema$1.Defect())
+}) {
+	constructor(props) {
+		super({
+			...props,
+			message: decodedProjectErrorMessage(props) ?? `Failed to list workspace entries in '${props.cwd}'.`
+		});
+	}
+};
+const ProjectReadFileInput = Schema$1.Struct({
+	cwd: TrimmedNonEmptyString,
+	relativePath: TrimmedNonEmptyString.check(Schema$1.isMaxLength(PROJECT_READ_FILE_PATH_MAX_LENGTH))
+});
+const ProjectReadFileResult = Schema$1.Struct({
+	relativePath: TrimmedNonEmptyString,
+	contents: Schema$1.String,
+	byteLength: NonNegativeInt,
+	truncated: Schema$1.Boolean
+});
+const ProjectFileFailure = Schema$1.Literals([
+	"workspace_path_outside_root",
+	"resolved_path_outside_root",
+	"path_not_file",
+	"binary_file",
+	"operation_failed"
+]);
+const ProjectFileOperation = Schema$1.Literals([
+	"realpath-workspace-root",
+	"realpath-target",
+	"open",
+	"stat",
+	"read",
+	"close",
+	"make-directory",
+	"write-file"
+]);
+var ProjectReadFileError = class extends Schema$1.TaggedErrorClass()("ProjectReadFileError", {
+	cwd: Schema$1.optional(TrimmedNonEmptyString),
+	relativePath: Schema$1.optional(TrimmedNonEmptyString),
+	failure: Schema$1.optional(ProjectFileFailure),
+	resolvedPath: Schema$1.optional(TrimmedNonEmptyString),
+	resolvedWorkspaceRoot: Schema$1.optional(TrimmedNonEmptyString),
+	operation: Schema$1.optional(ProjectFileOperation),
+	operationPath: Schema$1.optional(TrimmedNonEmptyString),
+	message: TrimmedNonEmptyString,
+	cause: Schema$1.optional(Schema$1.Defect())
+}) {
+	constructor(props) {
+		super({
+			...props,
+			message: decodedProjectErrorMessage(props) ?? `Failed to read workspace file '${props.relativePath}' in '${props.cwd}'.`
+		});
+	}
+};
+const ProjectWriteFileInput = Schema$1.Struct({
+	cwd: TrimmedNonEmptyString,
+	relativePath: TrimmedNonEmptyString.check(Schema$1.isMaxLength(PROJECT_WRITE_FILE_PATH_MAX_LENGTH)),
+	contents: Schema$1.String
+});
+const ProjectWriteFileResult = Schema$1.Struct({ relativePath: TrimmedNonEmptyString });
+var ProjectWriteFileError = class extends Schema$1.TaggedErrorClass()("ProjectWriteFileError", {
+	cwd: Schema$1.optional(TrimmedNonEmptyString),
+	relativePath: Schema$1.optional(TrimmedNonEmptyString),
+	failure: Schema$1.optional(ProjectFileFailure),
+	resolvedPath: Schema$1.optional(TrimmedNonEmptyString),
+	resolvedWorkspaceRoot: Schema$1.optional(TrimmedNonEmptyString),
+	operation: Schema$1.optional(ProjectFileOperation),
+	operationPath: Schema$1.optional(TrimmedNonEmptyString),
+	message: TrimmedNonEmptyString,
+	cause: Schema$1.optional(Schema$1.Defect())
+}) {
+	constructor(props) {
+		super({
+			...props,
+			message: decodedProjectErrorMessage(props) ?? `Failed to write workspace file '${props.relativePath}' in '${props.cwd}'.`
+		});
+	}
+};
+//#endregion
 //#region ../../packages/contracts/src/agentAsset.ts
 /**
 * User-scope agent assets — the things that make an agent behave the same on
@@ -12030,6 +12092,65 @@ var _036_TaskRepositoryKey_default = Effect.gen(function* () {
   `;
 });
 //#endregion
+//#region src/persistence/Migrations/037_TaskReadableIds.ts
+/**
+* Human-readable task ids (`T-1`, `P4-12`).
+*
+* `task_sequences` holds one row per prefix with the highest number ever
+* handed out. It only grows: deleting a task does not return its number, so a
+* readable id, once uttered, never comes to mean a different task.
+*
+* Existing rows are backfilled with the default `T` prefix in creation order.
+* Their projects' prefixes are deliberately not consulted — a prefix lives in
+* the project's checked-in `p4.json`, and a migration that shells out to read
+* workspaces (which may no longer be on disk) is exactly what a migration
+* should not be. New tasks pick up their project's prefix from creation on.
+*/
+var _037_TaskReadableIds_default = Effect.gen(function* () {
+	const sql = yield* SqlClient.SqlClient;
+	yield* sql`
+    CREATE TABLE IF NOT EXISTS task_sequences (
+      prefix TEXT PRIMARY KEY,
+      last_seq INTEGER NOT NULL
+    )
+  `;
+	yield* sql`ALTER TABLE tasks ADD COLUMN readable_id TEXT`;
+	yield* sql`
+    UPDATE tasks
+    SET readable_id = 'T-' || (
+      SELECT COUNT(*)
+      FROM tasks AS earlier
+      WHERE earlier.created_at < tasks.created_at
+        OR (earlier.created_at = tasks.created_at AND earlier.task_id <= tasks.task_id)
+    )
+    WHERE readable_id IS NULL
+  `;
+	yield* sql`
+    INSERT INTO task_sequences (prefix, last_seq)
+    SELECT 'T', COUNT(*) FROM tasks
+    WHERE true
+    ON CONFLICT (prefix) DO UPDATE SET last_seq = MAX(last_seq, excluded.last_seq)
+  `;
+	yield* sql`
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_tasks_readable_id
+    ON tasks(readable_id)
+  `;
+});
+//#endregion
+//#region src/persistence/Migrations/038_TaskOrderKeys.ts
+/**
+* Manual board position (`order_key`): a lexicographic fractional key written
+* when a card is dragged to a position, so one move rewrites one row.
+*
+* Existing rows are deliberately not backfilled. A null key means "never placed
+* by hand", and the board's comparator falls back to the old priority/recency
+* order for those - so a board nobody has dragged on looks exactly as it did
+* before this migration.
+*/
+var _038_TaskOrderKeys_default = Effect.gen(function* () {
+	yield* (yield* SqlClient.SqlClient)`ALTER TABLE tasks ADD COLUMN order_key TEXT`;
+});
+//#endregion
 //#region src/persistence/Migrations.ts
 /**
 * MigrationsLive - Migration runner with inline loader
@@ -12230,6 +12351,16 @@ const migrationEntries = [
 		36,
 		"TaskRepositoryKey",
 		_036_TaskRepositoryKey_default
+	],
+	[
+		37,
+		"TaskReadableIds",
+		_037_TaskReadableIds_default
+	],
+	[
+		38,
+		"TaskOrderKeys",
+		_038_TaskOrderKeys_default
 	]
 ];
 const makeMigrationLoader = (throughId) => Migrator.fromRecord(Object.fromEntries(migrationEntries.filter(([id]) => throughId === void 0 || id <= throughId).map(([id, name, migration]) => [`${id}_${name}`, migration])));
@@ -13853,6 +13984,7 @@ const TaskListQuery = Schema$1.Struct({
 });
 const TASK_COLUMNS = `
   task_id AS "taskId",
+  readable_id AS "readableId",
   project_id AS "projectId",
   repository_key AS "repositoryKey",
   thread_id AS "threadId",
@@ -13862,6 +13994,7 @@ const TASK_COLUMNS = `
   priority,
   assignee,
   labels_json AS "labels",
+  order_key AS "orderKey",
   created_at AS "createdAt",
   updated_at AS "updatedAt"
 `;
@@ -13874,6 +14007,7 @@ const makeTaskRepository = Effect.gen(function* () {
 		execute: (row) => sql`
         INSERT INTO tasks (
           task_id,
+          readable_id,
           project_id,
           repository_key,
           thread_id,
@@ -13883,11 +14017,13 @@ const makeTaskRepository = Effect.gen(function* () {
           priority,
           assignee,
           labels_json,
+          order_key,
           created_at,
           updated_at
         )
         VALUES (
           ${row.taskId},
+          ${row.readableId},
           ${row.projectId},
           ${row.repositoryKey},
           ${row.threadId},
@@ -13897,11 +14033,13 @@ const makeTaskRepository = Effect.gen(function* () {
           ${row.priority},
           ${row.assignee},
           ${JSON.stringify(row.labels)},
+          ${row.orderKey},
           ${row.createdAt},
           ${row.updatedAt}
         )
         ON CONFLICT (task_id)
         DO UPDATE SET
+          readable_id = excluded.readable_id,
           project_id = excluded.project_id,
           repository_key = excluded.repository_key,
           thread_id = excluded.thread_id,
@@ -13911,6 +14049,7 @@ const makeTaskRepository = Effect.gen(function* () {
           priority = excluded.priority,
           assignee = excluded.assignee,
           labels_json = excluded.labels_json,
+          order_key = excluded.order_key,
           created_at = excluded.created_at,
           updated_at = excluded.updated_at
       `
@@ -13920,6 +14059,26 @@ const makeTaskRepository = Effect.gen(function* () {
 		Result: TaskDbRow,
 		execute: ({ taskId }) => sql`SELECT ${sql.literal(TASK_COLUMNS)} FROM tasks WHERE task_id = ${taskId}`
 	});
+	const getTaskRowByReadableId = SqlSchema.findOneOption({
+		Request: Schema$1.String,
+		Result: TaskDbRow,
+		execute: (readableId) => sql`SELECT ${sql.literal(TASK_COLUMNS)} FROM tasks WHERE readable_id = ${readableId}`
+	});
+	/**
+	* Take the next number for a prefix, creating the sequence at 1 on first
+	* use. The row is never reset or decremented - a deleted task's number is
+	* gone - which is what makes a readable id safe to say out loud.
+	*/
+	const allocateReadableIdSeq = SqlSchema.findAll({
+		Request: Schema$1.Struct({ prefix: Schema$1.String }),
+		Result: Schema$1.Struct({ lastSeq: Schema$1.Int }),
+		execute: ({ prefix }) => sql`
+        INSERT INTO task_sequences (prefix, last_seq)
+        VALUES (${prefix}, 1)
+        ON CONFLICT (prefix) DO UPDATE SET last_seq = last_seq + 1
+        RETURNING last_seq AS "lastSeq"
+      `
+	});
 	const listTaskRows = SqlSchema.findAll({
 		Request: TaskListQuery,
 		Result: TaskDbRow,
@@ -13942,7 +14101,31 @@ const makeTaskRepository = Effect.gen(function* () {
 		type: "upserted",
 		task: row
 	})));
+	/**
+	* The allocation and the insert share one transaction on purpose: a number
+	* taken outside it would either be lost on a failed insert (a gap nobody
+	* caused) or, worse, handed to two concurrent creates.
+	*/
+	const create = (row, readableIdPrefix) => sql.withTransaction(Effect.gen(function* () {
+		const prefix = readableIdPrefix.toUpperCase();
+		const seq = (yield* allocateReadableIdSeq({ prefix }))[0]?.lastSeq;
+		if (seq === void 0) return yield* new PersistenceSqlError({
+			operation: "TaskRepository.create:allocate",
+			detail: "the sequence upsert returned no row",
+			cause: null
+		});
+		const task = {
+			...row,
+			readableId: `${prefix}-${seq}`
+		};
+		yield* upsertTaskRow(task);
+		return task;
+	})).pipe(Effect.mapError(toPersistenceSqlError("TaskRepository.create:query")), Effect.tap((task) => publish({
+		type: "upserted",
+		task
+	})));
 	const getById = (input) => getTaskRow(input).pipe(Effect.mapError(toPersistenceSqlError("TaskRepository.getById:query")));
+	const getByReadableId = (readableId) => getTaskRowByReadableId(readableId.toUpperCase()).pipe(Effect.mapError(toPersistenceSqlError("TaskRepository.getByReadableId:query")));
 	const list = (filter) => listTaskRows({
 		projectId: filter.projectId ?? null,
 		repositoryKey: filter.repositoryKey ?? null,
@@ -13964,6 +14147,7 @@ const makeTaskRepository = Effect.gen(function* () {
 			...input.priority !== void 0 ? { priority: input.priority } : {},
 			...input.assignee !== void 0 ? { assignee: input.assignee } : {},
 			...input.labels !== void 0 ? { labels: input.labels } : {},
+			...input.orderKey !== void 0 ? { orderKey: input.orderKey } : {},
 			updatedAt
 		};
 		yield* upsertTaskRow(updated);
@@ -14001,6 +14185,7 @@ const makeTaskRepository = Effect.gen(function* () {
 			...input.patch.priority !== void 0 ? { priority: input.patch.priority } : {},
 			...input.patch.assignee !== void 0 ? { assignee: input.patch.assignee } : {},
 			...input.patch.labels !== void 0 ? { labels: input.patch.labels } : {},
+			...input.patch.orderKey !== void 0 ? { orderKey: input.patch.orderKey } : {},
 			updatedAt
 		};
 		yield* upsertTaskRow(updated);
@@ -14017,10 +14202,12 @@ const makeTaskRepository = Effect.gen(function* () {
 		taskId: input.taskId
 	})));
 	return {
+		create,
 		upsert,
 		patch,
 		patchIfStatus,
 		getById,
+		getByReadableId,
 		list,
 		deleteById,
 		streamChanges: Stream.fromPubSub(changes),
@@ -14109,12 +14296,13 @@ const getTaskRoute = HttpRouter.add("GET", "/tasks/:taskId", respondToHubFailure
 	yield* authenticateHubRequest();
 	const params = yield* HttpRouter.params;
 	const taskId = TaskId.make(params.taskId ?? "");
-	const found = yield* (yield* TaskRepository).getById({ taskId });
+	const tasks = yield* TaskRepository;
+	const found = isReadableTaskId(taskId) ? yield* tasks.getByReadableId(taskId) : yield* tasks.getById({ taskId });
 	return Option.isNone(found) ? notFound(taskId) : HttpServerResponse.jsonUnsafe(found.value);
 })));
 const createTaskRoute = HttpRouter.add("POST", "/tasks", respondToHubFailures(Effect.gen(function* () {
 	yield* authenticateHubRequest();
-	const input = yield* decodeOrInvalid(TaskCreateInput, "Request body does not match TaskCreateInput.")(yield* readJsonBody());
+	const input = yield* decodeOrInvalid(HubTaskCreateInput, "Request body does not match HubTaskCreateInput.")(yield* readJsonBody());
 	const tasks = yield* TaskRepository;
 	const crypto = yield* Crypto.Crypto;
 	const taskId = TaskId.make(yield* crypto.randomUUIDv4.pipe(Effect.orDie));
@@ -14130,11 +14318,12 @@ const createTaskRoute = HttpRouter.add("POST", "/tasks", respondToHubFailures(Ef
 		priority: input.priority ?? "none",
 		assignee: input.assignee ?? null,
 		labels: input.labels ?? [],
+		orderKey: input.orderKey ?? null,
 		createdAt: timestamp,
 		updatedAt: timestamp
 	};
-	yield* tasks.upsert(row);
-	return HttpServerResponse.jsonUnsafe(row, { status: 201 });
+	const task = yield* tasks.create(row, input.readableIdPrefix ?? "T");
+	return HttpServerResponse.jsonUnsafe(task, { status: 201 });
 })));
 const updateTaskRoute = HttpRouter.add("PATCH", "/tasks/:taskId", respondToHubFailures(Effect.gen(function* () {
 	yield* authenticateHubRequest();
@@ -14372,6 +14561,60 @@ var _003_AgentAssets_default = Effect.gen(function* () {
   `;
 });
 //#endregion
+//#region src/hub/Migrations/004_TaskReadableIds.ts
+/**
+* Human-readable task ids (`T-1`, `P4-12`).
+*
+* `task_sequences` holds one row per prefix with the highest number ever
+* handed out. It only grows: deleting a task does not return its number, so a
+* readable id, once uttered, never comes to mean a different task.
+*
+* Existing rows are backfilled with the default `T` prefix in creation order.
+* Prefixes cannot be consulted here at all: they live in each project's
+* checked-in `p4.json`, and the hub has no checkouts. New tasks arrive with a
+* prefix resolved by the submitting environment server.
+*/
+var _004_TaskReadableIds_default = Effect.gen(function* () {
+	const sql = yield* SqlClient.SqlClient;
+	yield* sql`
+    CREATE TABLE IF NOT EXISTS task_sequences (
+      prefix TEXT PRIMARY KEY,
+      last_seq INTEGER NOT NULL
+    )
+  `;
+	yield* sql`ALTER TABLE tasks ADD COLUMN readable_id TEXT`;
+	yield* sql`
+    UPDATE tasks
+    SET readable_id = 'T-' || (
+      SELECT COUNT(*)
+      FROM tasks AS earlier
+      WHERE earlier.created_at < tasks.created_at
+        OR (earlier.created_at = tasks.created_at AND earlier.task_id <= tasks.task_id)
+    )
+    WHERE readable_id IS NULL
+  `;
+	yield* sql`
+    INSERT INTO task_sequences (prefix, last_seq)
+    SELECT 'T', COUNT(*) FROM tasks
+    WHERE true
+    ON CONFLICT (prefix) DO UPDATE SET last_seq = MAX(last_seq, excluded.last_seq)
+  `;
+	yield* sql`
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_tasks_readable_id
+    ON tasks(readable_id)
+  `;
+});
+//#endregion
+//#region src/hub/Migrations/005_TaskOrderKeys.ts
+/**
+* Manual board position (`order_key`), mirroring the environment server's
+* migration 038: a lexicographic fractional key written when a card is dragged
+* to a position. No backfill - null falls back to priority/recency order.
+*/
+var _005_TaskOrderKeys_default = Effect.gen(function* () {
+	yield* (yield* SqlClient.SqlClient)`ALTER TABLE tasks ADD COLUMN order_key TEXT`;
+});
+//#endregion
 //#region src/hub/Migrations.ts
 /**
 * Hub migrations.
@@ -14397,6 +14640,16 @@ const hubMigrationEntries = [
 		3,
 		"AgentAssets",
 		_003_AgentAssets_default
+	],
+	[
+		4,
+		"TaskReadableIds",
+		_004_TaskReadableIds_default
+	],
+	[
+		5,
+		"TaskOrderKeys",
+		_005_TaskOrderKeys_default
 	]
 ];
 const hubMigrationLoader = Migrator.fromRecord(Object.fromEntries(hubMigrationEntries.map(([id, name, migration]) => [`${id}_${name}`, migration])));
@@ -32038,6 +32291,8 @@ const normalizeDispatchCommand = (command) => Effect.gen(function* () {
 * presentation and is not.
 *
 * The id and timestamp are passed in so this stays pure and holds no clock.
+* The readable id is absent on purpose: the store allocates it at insert time,
+* inside the same transaction as the sequence bump.
 */
 const buildTaskRow = (input, taskId, timestamp, repositoryKey = null) => ({
 	taskId,
@@ -32050,6 +32305,7 @@ const buildTaskRow = (input, taskId, timestamp, repositoryKey = null) => ({
 	priority: input.priority ?? "none",
 	assignee: input.assignee ?? null,
 	labels: input.labels ?? [],
+	orderKey: null,
 	createdAt: timestamp,
 	updatedAt: timestamp
 });
@@ -32073,6 +32329,23 @@ const resolveTaskRepositoryKey = Effect.fn("taskBoard.resolveRepositoryKey")(fun
 	return (yield* (yield* RepositoryIdentityResolver).resolve(project.value.workspaceRoot))?.canonicalKey ?? null;
 });
 /**
+* Resolve the readable-id prefix for a task's project.
+*
+* The prefix lives in the project's checked-in `p4.json` (`taskPrefix`), not in
+* this server's database: it is a property of the repository, agreed on by
+* everyone who clones it, exactly like the scripts beside it. A task with no
+* project, a removed project, or a `p4.json` without the field all fall back to
+* the default `T` - filing the task always beats refusing it over a label.
+*/
+const resolveTaskReadableIdPrefix = Effect.fn("taskBoard.resolveReadableIdPrefix")(function* (projectId) {
+	if (projectId == null) return "T";
+	const project = yield* (yield* ProjectionProjectRepository).getById({ projectId }).pipe(Effect.catchCause(() => Effect.succeed(Option.none())));
+	if (Option.isNone(project)) return "T";
+	const file = yield* (yield* P4ProjectFileLoader).load(project.value.workspaceRoot);
+	if (Option.isNone(file) || file.value.taskPrefix === void 0) return "T";
+	return file.value.taskPrefix.toUpperCase();
+});
+/**
 * Everything that decides whether a task can be started, as one pure function.
 *
 * Kept out of the RPC handler because the three refusals are the whole of the
@@ -42697,9 +42970,12 @@ const makeWsRpcLayer = (currentSession, previewAutomationBroker) => WsRpcGroup.t
 		[WS_METHODS.tasksList]: (filter) => observeRpcEffect$1(WS_METHODS.tasksList, taskRepository.list(filter).pipe(Effect.catch(toTaskStoreError("tasks.list")), Effect.map((tasks) => ({ tasks }))), { "rpc.aggregate": "tasks" }),
 		[WS_METHODS.tasksGet]: ({ taskId }) => observeRpcEffect$1(WS_METHODS.tasksGet, taskRepository.getById({ taskId }).pipe(Effect.catch(toTaskStoreError("tasks.get")), Effect.map((found) => ({ task: Option.getOrNull(found) }))), { "rpc.aggregate": "tasks" }),
 		[WS_METHODS.tasksCreate]: (input) => observeRpcEffect$1(WS_METHODS.tasksCreate, Effect.gen(function* () {
-			const row = buildTaskRow(input, TaskId.make(yield* crypto.randomUUIDv4.pipe(Effect.orDie)), yield* nowIso$5, yield* resolveTaskRepositoryKey(input.projectId));
-			yield* taskRepository.upsert(row).pipe(Effect.catch(toTaskStoreError("tasks.create")));
-			return { task: row };
+			const taskId = TaskId.make(yield* crypto.randomUUIDv4.pipe(Effect.orDie));
+			const timestamp = yield* nowIso$5;
+			const repositoryKey = yield* resolveTaskRepositoryKey(input.projectId);
+			const readableIdPrefix = yield* resolveTaskReadableIdPrefix(input.projectId);
+			const row = buildTaskRow(input, taskId, timestamp, repositoryKey);
+			return { task: yield* taskRepository.create(row, readableIdPrefix).pipe(Effect.catch(toTaskStoreError("tasks.create"))) };
 		}), { "rpc.aggregate": "tasks" }),
 		[WS_METHODS.tasksUpdate]: (input) => observeRpcEffect$1(WS_METHODS.tasksUpdate, Effect.gen(function* () {
 			const timestamp = yield* nowIso$5;
@@ -43010,12 +43286,13 @@ const websocketRpcRouteLayer = Layer.unwrap(Effect.gen(function* () {
 	const serverSelfUpdate = yield* ServerSelfUpdate;
 	const taskRepository = yield* TaskRepository;
 	const projectionProjects = yield* ProjectionProjectRepository;
+	const p4ProjectFileLoader = yield* P4ProjectFileLoader;
 	return HttpRouter.add("GET", "/ws", Effect.gen(function* () {
 		const request = yield* HttpServerRequest.HttpServerRequest;
 		const serverAuth = yield* EnvironmentAuth;
 		const sessions = yield* SessionStore;
 		const session = yield* serverAuth.authenticateWebSocketUpgrade(request).pipe(Effect.catchIf(isServerAuthCredentialError, (error) => failEnvironmentAuthInvalid(serverAuthCredentialReason(error))), Effect.catchIf(isServerAuthInternalError, (error) => failEnvironmentInternal("internal_error", error)));
-		const rpcWebSocketHttpEffect = yield* RpcServer.toHttpEffectWebsocket(WsRpcGroup, { disableTracing: true }).pipe(Effect.provide(makeWsRpcLayer(session, previewAutomationBroker).pipe(Layer.provideMerge(RpcSerialization.layerJson), Layer.provide(layer$33), Layer.provide(Layer.succeed(ServerSelfUpdate, serverSelfUpdate)), Layer.provide(Layer.succeed(TaskRepository, taskRepository)), Layer.provide(Layer.succeed(ProjectionProjectRepository, projectionProjects)), Layer.provide(layer$5.pipe(Layer.provide(layer$14.pipe(Layer.provide(Layer.mergeAll(layer$22, layer$20, layer$18, layer$16)), Layer.provideMerge(layer$38), Layer.provide(layer$36.pipe(Layer.provide(layer$37))))), Layer.provide(layer$39))))));
+		const rpcWebSocketHttpEffect = yield* RpcServer.toHttpEffectWebsocket(WsRpcGroup, { disableTracing: true }).pipe(Effect.provide(makeWsRpcLayer(session, previewAutomationBroker).pipe(Layer.provideMerge(RpcSerialization.layerJson), Layer.provide(layer$33), Layer.provide(Layer.succeed(ServerSelfUpdate, serverSelfUpdate)), Layer.provide(Layer.succeed(TaskRepository, taskRepository)), Layer.provide(Layer.succeed(ProjectionProjectRepository, projectionProjects)), Layer.provide(Layer.succeed(P4ProjectFileLoader, p4ProjectFileLoader)), Layer.provide(layer$5.pipe(Layer.provide(layer$14.pipe(Layer.provide(Layer.mergeAll(layer$22, layer$20, layer$18, layer$16)), Layer.provideMerge(layer$38), Layer.provide(layer$36.pipe(Layer.provide(layer$37))))), Layer.provide(layer$39))))));
 		return yield* Effect.acquireUseRelease(sessions.markConnected(session.sessionId), () => rpcWebSocketHttpEffect, () => sessions.markDisconnected(session.sessionId));
 	}).pipe(Effect.catchTags({
 		EnvironmentAuthInvalidError: HttpServerRespondable.toResponse,
@@ -43120,17 +43397,16 @@ const makeRemoteTaskRepository = Effect.fn("makeRemoteTaskRepository")(function*
 		return Option.some(yield* response.json.pipe(Effect.flatMap(decodeTask), Effect.mapError(() => hubUnavailable("getById", "the response did not match the contract"))));
 	});
 	/**
-	* Upsert is a create here, and that is a real difference from the local
-	* store.
-	*
-	* The hub mints its own ids and timestamps, so a row written through this
-	* comes back with the hub's version of both. The caller's `taskId` is not
-	* carried: honouring it would need a hub route that takes one, and inventing
-	* that quietly would let two servers mint colliding ids.
+	* Both writes here POST the hub's create route, and that is a real
+	* difference from the local store: the hub mints its own ids, timestamps and
+	* readable id, so a row written through this comes back with the hub's
+	* version of all three. The caller's `taskId` is not carried - honouring it
+	* would need a hub route that takes one, and inventing that quietly would
+	* let two servers mint colliding ids.
 	*/
-	const upsert = (row) => Effect.gen(function* () {
-		const settings = yield* requireSettings("upsert");
-		const response = yield* send("upsert", settings, HttpClientRequest.bodyJsonUnsafe(HttpClientRequest.post(`${settings.baseUrl}/tasks`), {
+	const postCreate = (operation, row, readableIdPrefix) => Effect.gen(function* () {
+		const settings = yield* requireSettings(operation);
+		const response = yield* send(operation, settings, HttpClientRequest.bodyJsonUnsafe(HttpClientRequest.post(`${settings.baseUrl}/tasks`), {
 			...row.projectId === null ? {} : { projectId: row.projectId },
 			...row.repositoryKey === null ? {} : { repositoryKey: row.repositoryKey },
 			...row.threadId === null ? {} : { threadId: row.threadId },
@@ -43139,15 +43415,25 @@ const makeRemoteTaskRepository = Effect.fn("makeRemoteTaskRepository")(function*
 			status: row.status,
 			priority: row.priority,
 			...row.assignee === null ? {} : { assignee: row.assignee },
-			labels: row.labels
+			labels: row.labels,
+			...row.orderKey === null ? {} : { orderKey: row.orderKey },
+			...readableIdPrefix === void 0 ? {} : { readableIdPrefix }
 		}));
-		if (response.status !== 201 && response.status !== 200) return yield* hubUnavailable("upsert", `status ${response.status}`);
-		const created = yield* response.json.pipe(Effect.flatMap(decodeTask), Effect.mapError(() => hubUnavailable("upsert", "the response did not match the contract")));
+		if (response.status !== 201 && response.status !== 200) return yield* hubUnavailable(operation, `status ${response.status}`);
+		const created = yield* response.json.pipe(Effect.flatMap(decodeTask), Effect.mapError(() => hubUnavailable(operation, "the response did not match the contract")));
 		yield* publish({
 			type: "upserted",
 			task: created
 		});
+		return created;
 	});
+	const create = (row, readableIdPrefix) => postCreate("create", row, readableIdPrefix);
+	const upsert = (row) => postCreate("upsert", row).pipe(Effect.asVoid);
+	/**
+	* Served by the same hub route as `getById`: readable ids and UUIDs are
+	* disjoint by shape, so the hub dispatches on what it is handed.
+	*/
+	const getByReadableId = (readableId) => getById({ taskId: TaskId.make(readableId) });
 	const patch = (input) => Effect.gen(function* () {
 		const settings = yield* requireSettings("patch");
 		const { taskId, ...fields } = input;
@@ -43222,10 +43508,12 @@ const makeRemoteTaskRepository = Effect.fn("makeRemoteTaskRepository")(function*
 	}).pipe(Effect.ignoreCause({ log: true }));
 	yield* Effect.forever(pollOnce.pipe(Effect.andThen(Effect.sleep(POLL_INTERVAL)))).pipe(Effect.forkScoped);
 	return {
+		create,
 		upsert,
 		patch,
 		patchIfStatus,
 		getById,
+		getByReadableId,
 		list,
 		deleteById,
 		streamChanges: Stream.fromPubSub(changes),
@@ -43275,10 +43563,12 @@ const makeRoutedTaskRepository = Effect.gen(function* () {
 	*/
 	const pick = usingHub.pipe(Effect.map((hub) => hub ? remote : local));
 	return {
+		create: (row, readableIdPrefix) => pick.pipe(Effect.flatMap((repository) => repository.create(row, readableIdPrefix))),
 		upsert: (row) => pick.pipe(Effect.flatMap((repository) => repository.upsert(row))),
 		patch: (input, updatedAt) => pick.pipe(Effect.flatMap((repository) => repository.patch(input, updatedAt))),
 		patchIfStatus: (input, updatedAt) => pick.pipe(Effect.flatMap((repository) => repository.patchIfStatus(input, updatedAt))),
 		getById: (input) => pick.pipe(Effect.flatMap((repository) => repository.getById(input))),
+		getByReadableId: (readableId) => pick.pipe(Effect.flatMap((repository) => repository.getByReadableId(readableId))),
 		list: (filter) => pick.pipe(Effect.flatMap((repository) => repository.list(filter))),
 		deleteById: (input) => pick.pipe(Effect.flatMap((repository) => repository.deleteById(input))),
 		get streamChanges() {
@@ -81083,8 +81373,15 @@ const writeDependencies = [
 	ProjectionProjectRepository,
 	RepositoryIdentityResolver
 ];
-/** `task_create` also mints the task id, so it needs the crypto service. */
-const createDependencies = [...writeDependencies, Crypto.Crypto];
+/**
+* `task_create` also mints the task id (crypto) and resolves the readable-id
+* prefix from the project's checked-in `p4.json` (the file loader).
+*/
+const createDependencies = [
+	...writeDependencies,
+	Crypto.Crypto,
+	P4ProjectFileLoader
+];
 const TaskListResult = Schema$1.Struct({ tasks: Schema$1.Array(Task) });
 const TaskListTool = Tool.make("task_list", {
 	description: "List tasks on the board, most recently updated first. Every filter is optional and they combine with AND; omit all of them to list every task. Use this to find work rather than guessing task ids.",
@@ -81094,7 +81391,7 @@ const TaskListTool = Tool.make("task_list", {
 	dependencies
 }).annotate(Tool.Title, "List tasks").annotate(Tool.Readonly, true).annotate(Tool.Destructive, false).annotate(Tool.Idempotent, true);
 const TaskGetTool = Tool.make("task_get", {
-	description: "Read a single task by id, including its body, labels and linked thread.",
+	description: "Read a single task by id, including its body, labels and linked thread. Accepts either the UUID or the readable id (e.g. T-3, P4-12).",
 	parameters: TaskGetInput,
 	success: Task,
 	failure: TaskToolError,
@@ -81144,6 +81441,15 @@ const TaskToolkit = Toolkit.make(TaskListTool, TaskGetTool, TaskCurrentTool, Tas
 //#endregion
 //#region src/mcp/toolkits/tasks/handlers.ts
 const nowIso$1 = Effect.map(DateTime.now, DateTime.formatIso);
+/**
+* Agents reference tasks by whichever id they have seen, so any `taskId`
+* parameter accepts the readable id (`P4-12`) as well as the UUID. The two are
+* disjoint by shape, which is what makes the dispatch safe.
+*/
+const findTask = (taskId) => Effect.gen(function* () {
+	const tasks = yield* TaskRepository;
+	return isReadableTaskId(taskId) ? yield* tasks.getByReadableId(taskId) : yield* tasks.getById({ taskId });
+});
 const TaskToolkitHandlersLive = TaskToolkit.toLayer({
 	task_list: (input) => Effect.gen(function* () {
 		yield* requireTaskCapability();
@@ -81151,7 +81457,7 @@ const TaskToolkitHandlersLive = TaskToolkit.toLayer({
 	}),
 	task_get: (input) => Effect.gen(function* () {
 		yield* requireTaskCapability();
-		const found = yield* (yield* TaskRepository).getById({ taskId: input.taskId }).pipe(Effect.catch(toTaskStoreError("task_get")));
+		const found = yield* findTask(input.taskId).pipe(Effect.catch(toTaskStoreError("task_get")));
 		if (Option.isNone(found)) return yield* new TaskNotFoundError({ taskId: input.taskId });
 		return found.value;
 	}),
@@ -81167,16 +81473,25 @@ const TaskToolkitHandlersLive = TaskToolkit.toLayer({
 		yield* requireTaskCapability();
 		const tasks = yield* TaskRepository;
 		const crypto = yield* Crypto.Crypto;
-		const row = buildTaskRow(input, TaskId.make(yield* crypto.randomUUIDv4.pipe(Effect.orDie)), yield* nowIso$1, yield* resolveTaskRepositoryKey(input.projectId));
-		yield* tasks.upsert(row).pipe(Effect.catch(toTaskStoreError("task_create")));
-		return row;
+		const taskId = TaskId.make(yield* crypto.randomUUIDv4.pipe(Effect.orDie));
+		const timestamp = yield* nowIso$1;
+		const repositoryKey = yield* resolveTaskRepositoryKey(input.projectId);
+		const readableIdPrefix = yield* resolveTaskReadableIdPrefix(input.projectId);
+		const row = buildTaskRow(input, taskId, timestamp, repositoryKey);
+		return yield* tasks.create(row, readableIdPrefix).pipe(Effect.catch(toTaskStoreError("task_create")));
 	}),
 	task_update: (input) => Effect.gen(function* () {
 		yield* requireTaskCapability();
 		const tasks = yield* TaskRepository;
 		const timestamp = yield* nowIso$1;
-		const patch = input.projectId === void 0 ? input : {
+		const taskId = isReadableTaskId(input.taskId) ? Option.getOrNull(yield* findTask(input.taskId).pipe(Effect.catch(toTaskStoreError("task_update"))))?.taskId : input.taskId;
+		if (taskId === void 0) return yield* new TaskNotFoundError({ taskId: input.taskId });
+		const patch = input.projectId === void 0 ? {
+			...input,
+			taskId
+		} : {
 			...input,
+			taskId,
 			repositoryKey: yield* resolveTaskRepositoryKey(input.projectId)
 		};
 		const patched = yield* tasks.patch(patch, timestamp).pipe(Effect.catch(toTaskStoreError("task_update")));
@@ -84890,7 +85205,7 @@ const RuntimeDependenciesLive = ReactorLayerLive.pipe(Layer.provideMerge(Checkpo
 */
 const AssetSyncLive = layer$54.pipe(Layer.provideMerge(layer$55), Layer.provideMerge(layer$56));
 const RuntimeServicesLive = layer$44.pipe(Layer.provideMerge(AssetSyncLive), Layer.provideMerge(RuntimeDependenciesLive));
-const makeRoutesLayer = Layer.mergeAll(Layer.mergeAll(HttpApiBuilder.layer(EnvironmentHttpApi).pipe(Layer.provide(authHttpApiLayer), Layer.provide(orchestrationHttpApiLayer), Layer.provide(serverEnvironmentHttpApiLayer), Layer.provide(environmentAuthenticatedAuthLayer)), otlpTracesProxyRouteLayer, assetRouteLayer, staticAndDevRouteLayer, websocketRpcRouteLayer), layer.pipe(Layer.provide(layer$2))).pipe(Layer.provide(RoutedTaskRepositoryLive.pipe(Layer.provide(PersistenceLayerLive))), Layer.provide(ProjectionProjectRepositoryLive.pipe(Layer.provide(PersistenceLayerLive))), Layer.provide(layer$28), Layer.provide(layer$46), Layer.provide(browserApiCorsLayer), Layer.provide(httpCompressionLayer));
+const makeRoutesLayer = Layer.mergeAll(Layer.mergeAll(HttpApiBuilder.layer(EnvironmentHttpApi).pipe(Layer.provide(authHttpApiLayer), Layer.provide(orchestrationHttpApiLayer), Layer.provide(serverEnvironmentHttpApiLayer), Layer.provide(environmentAuthenticatedAuthLayer)), otlpTracesProxyRouteLayer, assetRouteLayer, staticAndDevRouteLayer, websocketRpcRouteLayer), layer.pipe(Layer.provide(layer$2))).pipe(Layer.provide(RoutedTaskRepositoryLive.pipe(Layer.provide(PersistenceLayerLive))), Layer.provide(ProjectionProjectRepositoryLive.pipe(Layer.provide(PersistenceLayerLive))), Layer.provide(layer$42), Layer.provide(layer$28), Layer.provide(layer$46), Layer.provide(browserApiCorsLayer), Layer.provide(httpCompressionLayer));
 const makeServerLayer = Layer.unwrap(Effect.gen(function* () {
 	const config = yield* ServerConfig$1;
 	yield* fixPath();