@oscharko-dev/keiko-contracts 0.2.8 → 0.2.9

package/dist/task-workspace.js

@@ -0,0 +1,1236 @@
+// Public type contracts for the task-scoped isolated workspace domain (Issue #444, Epic #443).
+// Ownership: the task-workspace domain — what a task-scoped isolated workspace IS, how a task binds
+// to it, its lifecycle state machine, drift/recovery semantics, and the read-only vs mutating
+// operation authority. Disjoint from the subsystems it DELEGATES to: it never re-implements Git
+// mutation (owned by git-delivery.ts, #470), editor/runtime context (owned by editor-agent.ts /
+// editor-session.ts, #1491), terminal mutation (keiko-tools terminal policy, ADR-0018), or workspace
+// discovery + path containment (owned by @oscharko-dev/keiko-workspace). The delegation boundary is
+// encoded as data in TASK_WORKSPACE_DELEGATED_SUBSYSTEMS so a second copy of any of those subsystems
+// is structurally prevented (AC4).
+//
+// Leaf-package rules (ADR-0019): pure types, frozen `as const` tables, and pure functions only. No IO,
+// no clock, no crypto, no randomness, and no imports of any @oscharko-dev/* package. Hashes, ids, and
+// correlation ids are produced by callers (opaque strings); timestamps are caller-provided ISO strings.
+// CONTENT-FREE invariant (SC3): every persisted/audit field is an opaque id/hash, a count, a boolean
+// flag, an enum, an ISO timestamp string, or a branch/path name — NEVER source text, secrets, tokens,
+// raw provider payloads, or unbounded command output. Enforced at runtime by rejecting any unknown
+// key against a closed allowlist in EVERY persisted-object validator — the audit event
+// (validateWorkspaceEvent / WORKSPACE_EVENT_ALLOWED_KEYS), the durable instance
+// (validateWorkspaceInstance / WORKSPACE_INSTANCE_ALLOWED_KEYS), the binding
+// (validateWorkspaceBinding / WORKSPACE_BINDING_ALLOWED_KEYS), and the activation intent
+// (validateWorkspaceActivation / WORKSPACE_ACTIVATION_ALLOWED_KEYS) — so a downstream persistence
+// layer that trusts `.ok` cannot store smuggled content through any shape.
+export const TASK_WORKSPACE_SCHEMA_VERSION = "1";
+// ─── Local type guards (copied per leaf convention; see git-repository.ts) ──────
+function isRecord(input) {
+    return typeof input === "object" && input !== null && !Array.isArray(input);
+}
+function isNonEmptyString(input) {
+    return typeof input === "string" && input.length > 0;
+}
+function isBoolean(input) {
+    return typeof input === "boolean";
+}
+// Collect "unknown key not allowed" reasons for a content-free object: any key outside the closed
+// allowlist is treated as an attempt to smuggle source text / secrets / tokens / raw payloads, so
+// the validator rejects it (SC3). Shared by the audit-event validator AND the persisted-object
+// validators (instance/binding/activation) so the content-free invariant is enforced uniformly
+// across the durable surface, not only the event stream.
+function unknownKeyReasons(input, allowedKeys) {
+    const reasons = [];
+    for (const key of Object.keys(input)) {
+        if (!allowedKeys.includes(key)) {
+            reasons.push(`unknown key not allowed (content-free): ${key}`);
+        }
+    }
+    return reasons;
+}
+export const TASK_WORKSPACE_LIFECYCLE_STATES = [
+    "provisioning",
+    "active",
+    "paused",
+    "handoff-ready",
+    "archived",
+    "merged",
+    "abandoned",
+    "recovery-required",
+    "failed",
+    "cleanup-pending",
+];
+export function isTaskWorkspaceLifecycleState(value) {
+    return (typeof value === "string" &&
+        TASK_WORKSPACE_LIFECYCLE_STATES.includes(value));
+}
+// ─── Legal transition matrix (AC2) ────────────────────────────────────────────────
+// Self-transitions (from === to) are ILLEGAL: no state lists itself as a successor.
+export const TASK_WORKSPACE_LEGAL_TRANSITIONS = {
+    provisioning: ["active", "recovery-required", "failed", "cleanup-pending"],
+    active: ["paused", "handoff-ready", "recovery-required", "failed", "cleanup-pending"],
+    paused: [
+        "active",
+        "handoff-ready",
+        "archived",
+        "abandoned",
+        "recovery-required",
+        "cleanup-pending",
+    ],
+    "handoff-ready": [
+        "active",
+        "merged",
+        "archived",
+        "abandoned",
+        "recovery-required",
+        "cleanup-pending",
+    ],
+    merged: ["archived", "cleanup-pending"],
+    archived: ["cleanup-pending"],
+    abandoned: ["cleanup-pending"],
+    "recovery-required": ["active", "paused", "failed", "abandoned", "cleanup-pending"],
+    failed: ["recovery-required", "abandoned", "cleanup-pending"],
+    "cleanup-pending": ["archived", "abandoned", "recovery-required"],
+};
+// `from`/`to` are guarded with isTaskWorkspaceLifecycleState before the table lookup so a
+// post-deserialization or wire-supplied non-state value (e.g. "", "__proto__", "constructor", a
+// number, null) fails CLOSED — returns false / [] — instead of throwing or resolving to a
+// prototype-chain value. This keeps every exported predicate throw-free on `unknown` input,
+// matching the sibling validators (ADR-0088 D6).
+export function isLegalTaskWorkspaceTransition(from, to) {
+    if (!isTaskWorkspaceLifecycleState(from) || !isTaskWorkspaceLifecycleState(to))
+        return false;
+    return TASK_WORKSPACE_LEGAL_TRANSITIONS[from].includes(to);
+}
+export function nextLegalTaskWorkspaceStates(from) {
+    if (!isTaskWorkspaceLifecycleState(from))
+        return [];
+    return TASK_WORKSPACE_LEGAL_TRANSITIONS[from];
+}
+export const TASK_WORKSPACE_TRANSITION_PRECONDITIONS = [
+    "lock-held-by-actor",
+    "path-contained",
+    "worktree-clean",
+    "branch-ready",
+    "provider-ready",
+    "operator-approval",
+];
+export function isTaskWorkspaceTransitionPrecondition(value) {
+    return (typeof value === "string" &&
+        TASK_WORKSPACE_TRANSITION_PRECONDITIONS.includes(value));
+}
+// Data table keyed `${from}->${to}`. Every LEGAL transition that carries a precondition is listed;
+// any legal transition absent from this table defaults to no preconditions ([]). All
+// `*->cleanup-pending` transitions require operator-approval. Illegal transitions never reach this
+// table — they are rejected first by validateTaskWorkspaceTransition.
+const TASK_WORKSPACE_TRANSITION_PRECONDITION_TABLE = {
+    "provisioning->active": ["lock-held-by-actor", "path-contained", "branch-ready"],
+    "provisioning->recovery-required": ["lock-held-by-actor"],
+    "provisioning->failed": [],
+    "provisioning->cleanup-pending": ["operator-approval"],
+    "active->paused": ["lock-held-by-actor"],
+    "active->handoff-ready": ["lock-held-by-actor", "worktree-clean"],
+    "active->recovery-required": [],
+    "active->failed": [],
+    "active->cleanup-pending": ["operator-approval"],
+    "paused->active": ["lock-held-by-actor", "path-contained"],
+    "paused->handoff-ready": ["lock-held-by-actor", "worktree-clean"],
+    "paused->archived": ["operator-approval"],
+    "paused->abandoned": ["operator-approval"],
+    "paused->recovery-required": [],
+    "paused->cleanup-pending": ["operator-approval"],
+    "handoff-ready->active": ["lock-held-by-actor", "path-contained"],
+    "handoff-ready->merged": ["provider-ready", "operator-approval"],
+    "handoff-ready->archived": ["operator-approval"],
+    "handoff-ready->abandoned": ["operator-approval"],
+    "handoff-ready->recovery-required": [],
+    "handoff-ready->cleanup-pending": ["operator-approval"],
+    "merged->archived": ["operator-approval"],
+    "merged->cleanup-pending": ["operator-approval"],
+    "archived->cleanup-pending": ["operator-approval"],
+    "abandoned->cleanup-pending": ["operator-approval"],
+    "recovery-required->active": ["lock-held-by-actor", "path-contained"],
+    "recovery-required->paused": ["lock-held-by-actor"],
+    "recovery-required->failed": [],
+    "recovery-required->abandoned": ["operator-approval"],
+    "recovery-required->cleanup-pending": ["operator-approval"],
+    "failed->recovery-required": [],
+    "failed->abandoned": ["operator-approval"],
+    "failed->cleanup-pending": ["operator-approval"],
+    "cleanup-pending->archived": ["lock-held-by-actor", "worktree-clean"],
+    "cleanup-pending->abandoned": ["operator-approval"],
+    "cleanup-pending->recovery-required": [],
+};
+export function requiredTaskWorkspaceTransitionPreconditions(from, to) {
+    return TASK_WORKSPACE_TRANSITION_PRECONDITION_TABLE[`${from}->${to}`] ?? [];
+}
+const PRECONDITION_CONTEXT_KEY = {
+    "lock-held-by-actor": "lockHeldByActor",
+    "path-contained": "pathContained",
+    "worktree-clean": "worktreeClean",
+    "branch-ready": "branchReady",
+    "provider-ready": "providerReady",
+    "operator-approval": "operatorApproved",
+};
+export function validateTaskWorkspaceTransition(input) {
+    const { from, to, context } = input;
+    if (!isLegalTaskWorkspaceTransition(from, to)) {
+        return { ok: false, reasons: [`illegal transition from ${from} to ${to}`] };
+    }
+    const reasons = [];
+    for (const precondition of requiredTaskWorkspaceTransitionPreconditions(from, to)) {
+        if (!context[PRECONDITION_CONTEXT_KEY[precondition]]) {
+            reasons.push(`unmet precondition: ${precondition}`);
+        }
+    }
+    return reasons.length === 0 ? { ok: true } : { ok: false, reasons };
+}
+export const TASK_WORKSPACE_HEALTH_STATES = [
+    "healthy",
+    "degraded",
+    "drifted",
+    "locked-out",
+    "missing",
+    "unknown",
+];
+export function isTaskWorkspaceHealth(value) {
+    return (typeof value === "string" && TASK_WORKSPACE_HEALTH_STATES.includes(value));
+}
+export const TASK_WORKSPACE_DRIFT_MARKERS = [
+    "worktree-missing",
+    "gitdir-mismatch",
+    "head-moved",
+    "branch-deleted",
+    "uncommitted-changes",
+    "lock-stale",
+    "path-escape",
+    "pointer-stale",
+];
+export function isTaskWorkspaceDriftMarker(value) {
+    return (typeof value === "string" &&
+        TASK_WORKSPACE_DRIFT_MARKERS.includes(value));
+}
+export const WORKSPACE_LOCK_REASONS = [
+    "provisioning",
+    "activation",
+    "mutation",
+    "repair",
+    "cleanup",
+];
+export function isWorkspaceLockReason(value) {
+    return typeof value === "string" && WORKSPACE_LOCK_REASONS.includes(value);
+}
+export const WORKSPACE_FAILURE_CLASSES = [
+    "retryable",
+    "repairable",
+    "blocked",
+    "policy-denied",
+    "terminal",
+];
+export function isWorkspaceFailureClass(value) {
+    return (typeof value === "string" && WORKSPACE_FAILURE_CLASSES.includes(value));
+}
+export const WORKSPACE_RECOVERY_STRATEGIES = [
+    "reconcile-pointer",
+    "recreate-worktree",
+    "reattach-branch",
+    "release-stale-lock",
+    "commit-or-stash-required",
+    "operator-repair",
+    "abandon-and-cleanup",
+];
+export function isWorkspaceRecoveryStrategy(value) {
+    return (typeof value === "string" &&
+        WORKSPACE_RECOVERY_STRATEGIES.includes(value));
+}
+export const TASK_WORKSPACE_SURFACES = [
+    "chat",
+    "files",
+    "terminal",
+    "browser",
+    "editor",
+    "runtime",
+    "git-delivery",
+    "review",
+];
+export function isWorkspaceSurface(value) {
+    return typeof value === "string" && TASK_WORKSPACE_SURFACES.includes(value);
+}
+export const WORKSPACE_EVENT_TYPES = [
+    "provisioned",
+    "activated",
+    "paused",
+    "resumed",
+    "handoff-prepared",
+    "merged",
+    "archived",
+    "abandoned",
+    "recovery-flagged",
+    "repaired",
+    "cleanup-requested",
+    "cleanup-completed",
+    "lock-acquired",
+    "lock-released",
+    "drift-detected",
+    "health-changed",
+    "transition-rejected",
+];
+export function isWorkspaceEventType(value) {
+    return typeof value === "string" && WORKSPACE_EVENT_TYPES.includes(value);
+}
+// The closed set of keys a WorkspaceEvent may carry. Any other key means an attempt to smuggle
+// source text / secrets / raw payloads through the audit stream, so the validator rejects it (SC3).
+export const WORKSPACE_EVENT_ALLOWED_KEYS = [
+    "schemaVersion",
+    "eventId",
+    "workspaceId",
+    "taskId",
+    "type",
+    "at",
+    "correlationId",
+    "fromState",
+    "toState",
+    "health",
+    "driftMarkers",
+    "lockId",
+];
+// eslint-disable-next-line complexity
+export function validateWorkspaceEvent(input) {
+    if (!isRecord(input))
+        return { ok: false, reasons: ["event must be an object"] };
+    const reasons = unknownKeyReasons(input, WORKSPACE_EVENT_ALLOWED_KEYS);
+    if (input.schemaVersion !== TASK_WORKSPACE_SCHEMA_VERSION)
+        reasons.push("schemaVersion invalid");
+    for (const key of ["eventId", "workspaceId", "taskId", "at", "correlationId"]) {
+        if (!isNonEmptyString(input[key]))
+            reasons.push(`${key} must be a non-empty string`);
+    }
+    if (!isWorkspaceEventType(input.type))
+        reasons.push("type invalid");
+    if (input.fromState !== undefined && !isTaskWorkspaceLifecycleState(input.fromState)) {
+        reasons.push("fromState invalid");
+    }
+    if (input.toState !== undefined && !isTaskWorkspaceLifecycleState(input.toState)) {
+        reasons.push("toState invalid");
+    }
+    if (input.health !== undefined && !isTaskWorkspaceHealth(input.health)) {
+        reasons.push("health invalid");
+    }
+    if (input.driftMarkers !== undefined) {
+        if (!Array.isArray(input.driftMarkers))
+            reasons.push("driftMarkers must be an array");
+        else if (!input.driftMarkers.every(isTaskWorkspaceDriftMarker)) {
+            reasons.push("driftMarkers contains an invalid marker");
+        }
+    }
+    if (input.lockId !== undefined && !isNonEmptyString(input.lockId)) {
+        reasons.push("lockId must be a non-empty string when present");
+    }
+    return reasons.length === 0 ? { ok: true } : { ok: false, reasons };
+}
+function validateWorkspaceLock(input, reasons) {
+    if (!isRecord(input)) {
+        reasons.push("lock must be an object or null");
+        return;
+    }
+    for (const key of ["lockId", "owner", "acquiredAt"]) {
+        if (!isNonEmptyString(input[key]))
+            reasons.push(`lock.${key} must be a non-empty string`);
+    }
+    if (!isWorkspaceLockReason(input.reason))
+        reasons.push("lock.reason invalid");
+    if (input.expiresAt !== undefined && !isNonEmptyString(input.expiresAt)) {
+        reasons.push("lock.expiresAt must be a non-empty string when present");
+    }
+}
+function validateRecoveryHints(input, reasons) {
+    if (!Array.isArray(input)) {
+        reasons.push("recoveryHints must be an array");
+        return;
+    }
+    input.forEach((hint, index) => {
+        if (!isRecord(hint)) {
+            reasons.push(`recoveryHints[${String(index)}] must be an object`);
+            return;
+        }
+        if (!isTaskWorkspaceDriftMarker(hint.marker)) {
+            reasons.push(`recoveryHints[${String(index)}].marker invalid`);
+        }
+        if (!isWorkspaceRecoveryStrategy(hint.strategy)) {
+            reasons.push(`recoveryHints[${String(index)}].strategy invalid`);
+        }
+        if (!isBoolean(hint.operatorActionRequired)) {
+            reasons.push(`recoveryHints[${String(index)}].operatorActionRequired must be a boolean`);
+        }
+    });
+}
+// The closed set of top-level keys a persisted WorkspaceInstance may carry. Enforced by
+// validateWorkspaceInstance so the durable record stays content-free (SC3): a #447 persistence layer
+// that trusts `validateWorkspaceInstance(input).ok` cannot store a record carrying a smuggled
+// `sourceDiff` / `commandOutput` / `tokenValue` field. Nested `lock` and `recoveryHints` shapes are
+// validated by their own helpers.
+export const WORKSPACE_INSTANCE_ALLOWED_KEYS = [
+    "schemaVersion",
+    "workspaceId",
+    "taskId",
+    "repositoryId",
+    "repositoryRoot",
+    "baseBranch",
+    "taskBranch",
+    "managedWorktreePath",
+    "gitdirIdentity",
+    "lifecycleState",
+    "health",
+    "lock",
+    "createdAt",
+    "updatedAt",
+    "lastVerifiedAt",
+    "lastVerifiedHead",
+    "driftMarkers",
+    "recoveryHints",
+    "auditCorrelationId",
+];
+// eslint-disable-next-line complexity
+export function validateWorkspaceInstance(input) {
+    if (!isRecord(input))
+        return { ok: false, reasons: ["instance must be an object"] };
+    const reasons = unknownKeyReasons(input, WORKSPACE_INSTANCE_ALLOWED_KEYS);
+    if (input.schemaVersion !== TASK_WORKSPACE_SCHEMA_VERSION)
+        reasons.push("schemaVersion invalid");
+    for (const key of [
+        "workspaceId",
+        "taskId",
+        "repositoryId",
+        "repositoryRoot",
+        "baseBranch",
+        "taskBranch",
+        "managedWorktreePath",
+        "gitdirIdentity",
+        "createdAt",
+        "updatedAt",
+        "auditCorrelationId",
+    ]) {
+        if (!isNonEmptyString(input[key]))
+            reasons.push(`${key} must be a non-empty string`);
+    }
+    if (!isTaskWorkspaceLifecycleState(input.lifecycleState))
+        reasons.push("lifecycleState invalid");
+    if (!isTaskWorkspaceHealth(input.health))
+        reasons.push("health invalid");
+    if (input.lock !== null)
+        validateWorkspaceLock(input.lock, reasons);
+    if (input.lastVerifiedAt !== undefined && !isNonEmptyString(input.lastVerifiedAt)) {
+        reasons.push("lastVerifiedAt must be a non-empty string when present");
+    }
+    if (input.lastVerifiedHead !== undefined && !isNonEmptyString(input.lastVerifiedHead)) {
+        reasons.push("lastVerifiedHead must be a non-empty string when present");
+    }
+    if (!Array.isArray(input.driftMarkers))
+        reasons.push("driftMarkers must be an array");
+    else if (!input.driftMarkers.every(isTaskWorkspaceDriftMarker)) {
+        reasons.push("driftMarkers contains an invalid marker");
+    }
+    validateRecoveryHints(input.recoveryHints, reasons);
+    return reasons.length === 0 ? { ok: true } : { ok: false, reasons };
+}
+// The closed set of keys a WorkspaceBinding may carry (content-free, SC3).
+export const WORKSPACE_BINDING_ALLOWED_KEYS = [
+    "schemaVersion",
+    "workspaceId",
+    "taskId",
+    "activeRoot",
+    "boundSurfaces",
+    "gitDeliveryRoot",
+    "editorProjectRoot",
+];
+// eslint-disable-next-line complexity
+export function validateWorkspaceBinding(input) {
+    if (!isRecord(input))
+        return { ok: false, reasons: ["binding must be an object"] };
+    const reasons = unknownKeyReasons(input, WORKSPACE_BINDING_ALLOWED_KEYS);
+    if (input.schemaVersion !== TASK_WORKSPACE_SCHEMA_VERSION)
+        reasons.push("schemaVersion invalid");
+    for (const key of [
+        "workspaceId",
+        "taskId",
+        "activeRoot",
+        "gitDeliveryRoot",
+        "editorProjectRoot",
+    ]) {
+        if (!isNonEmptyString(input[key]))
+            reasons.push(`${key} must be a non-empty string`);
+    }
+    if (!Array.isArray(input.boundSurfaces))
+        reasons.push("boundSurfaces must be an array");
+    else if (!input.boundSurfaces.every(isWorkspaceSurface)) {
+        reasons.push("boundSurfaces contains an invalid surface");
+    }
+    if (isNonEmptyString(input.activeRoot)) {
+        if (input.gitDeliveryRoot !== input.activeRoot) {
+            reasons.push("gitDeliveryRoot must equal activeRoot");
+        }
+        if (input.editorProjectRoot !== input.activeRoot) {
+            reasons.push("editorProjectRoot must equal activeRoot");
+        }
+    }
+    return reasons.length === 0 ? { ok: true } : { ok: false, reasons };
+}
+// The closed set of keys a WorkspaceActivation intent may carry (content-free, SC3).
+export const WORKSPACE_ACTIVATION_ALLOWED_KEYS = [
+    "schemaVersion",
+    "workspaceId",
+    "taskId",
+    "requestedBy",
+    "acquireLock",
+    "expectedLifecycleState",
+];
+export function validateWorkspaceActivation(input) {
+    if (!isRecord(input))
+        return { ok: false, reasons: ["activation must be an object"] };
+    const reasons = unknownKeyReasons(input, WORKSPACE_ACTIVATION_ALLOWED_KEYS);
+    if (input.schemaVersion !== TASK_WORKSPACE_SCHEMA_VERSION)
+        reasons.push("schemaVersion invalid");
+    for (const key of ["workspaceId", "taskId", "requestedBy"]) {
+        if (!isNonEmptyString(input[key]))
+            reasons.push(`${key} must be a non-empty string`);
+    }
+    if (!isBoolean(input.acquireLock))
+        reasons.push("acquireLock must be a boolean");
+    if (input.expectedLifecycleState !== undefined &&
+        !isTaskWorkspaceLifecycleState(input.expectedLifecycleState)) {
+        reasons.push("expectedLifecycleState invalid");
+    }
+    return reasons.length === 0 ? { ok: true } : { ok: false, reasons };
+}
+export const TASK_WORKSPACE_OPERATIONS = [
+    {
+        name: "discover",
+        authority: "read-only",
+        requiresLock: false,
+        requiresOperatorApproval: false,
+    },
+    {
+        name: "get-instance",
+        authority: "read-only",
+        requiresLock: false,
+        requiresOperatorApproval: false,
+    },
+    {
+        name: "get-health",
+        authority: "read-only",
+        requiresLock: false,
+        requiresOperatorApproval: false,
+    },
+    {
+        name: "resolve-binding",
+        authority: "read-only",
+        requiresLock: false,
+        requiresOperatorApproval: false,
+    },
+    {
+        name: "provision",
+        authority: "mutating-server-action",
+        requiresLock: true,
+        requiresOperatorApproval: false,
+    },
+    {
+        name: "activate",
+        authority: "mutating-server-action",
+        requiresLock: true,
+        requiresOperatorApproval: false,
+    },
+    {
+        name: "pause",
+        authority: "mutating-server-action",
+        requiresLock: false,
+        requiresOperatorApproval: false,
+    },
+    {
+        name: "resume",
+        authority: "mutating-server-action",
+        requiresLock: true,
+        requiresOperatorApproval: false,
+    },
+    {
+        name: "prepare-handoff",
+        authority: "mutating-server-action",
+        requiresLock: false,
+        requiresOperatorApproval: false,
+    },
+    {
+        name: "mark-merged",
+        authority: "mutating-server-action",
+        requiresLock: false,
+        requiresOperatorApproval: false,
+    },
+    {
+        name: "archive",
+        authority: "mutating-server-action",
+        requiresLock: false,
+        requiresOperatorApproval: false,
+    },
+    {
+        name: "abandon",
+        authority: "mutating-server-action",
+        requiresLock: false,
+        requiresOperatorApproval: false,
+    },
+    {
+        name: "flag-recovery",
+        authority: "mutating-server-action",
+        requiresLock: false,
+        requiresOperatorApproval: false,
+    },
+    {
+        name: "repair",
+        authority: "mutating-server-action",
+        requiresLock: true,
+        requiresOperatorApproval: true,
+    },
+    {
+        name: "request-cleanup",
+        authority: "mutating-server-action",
+        requiresLock: false,
+        requiresOperatorApproval: true,
+    },
+    {
+        name: "complete-cleanup",
+        authority: "mutating-server-action",
+        requiresLock: true,
+        requiresOperatorApproval: true,
+    },
+    {
+        name: "acquire-lock",
+        authority: "mutating-server-action",
+        requiresLock: false,
+        requiresOperatorApproval: false,
+    },
+    {
+        name: "release-lock",
+        authority: "mutating-server-action",
+        requiresLock: false,
+        requiresOperatorApproval: false,
+    },
+    {
+        name: "append-event",
+        authority: "read-only",
+        requiresLock: false,
+        requiresOperatorApproval: false,
+    },
+];
+export function taskWorkspaceOperation(name) {
+    return TASK_WORKSPACE_OPERATIONS.find((operation) => operation.name === name);
+}
+export function isReadOnlyTaskWorkspaceOperation(name) {
+    return taskWorkspaceOperation(name)?.authority === "read-only";
+}
+export function isMutatingTaskWorkspaceOperation(name) {
+    return taskWorkspaceOperation(name)?.authority === "mutating-server-action";
+}
+export const TASK_WORKSPACE_DELEGATED_SUBSYSTEMS = [
+    { concern: "git-mutation", owner: "git-delivery (#470)" },
+    { concern: "editor-runtime-context", owner: "editor-agent / editor-session (#1491)" },
+    { concern: "terminal-mutation", owner: "keiko-tools terminal policy (ADR-0018) — unchanged" },
+    {
+        concern: "workspace-discovery-and-containment",
+        owner: "@oscharko-dev/keiko-workspace",
+    },
+];
+export function isDelegatedTaskWorkspaceConcern(concern) {
+    return (typeof concern === "string" &&
+        TASK_WORKSPACE_DELEGATED_SUBSYSTEMS.some((entry) => entry.concern === concern));
+}
+export function taskWorkspaceDelegatedOwner(concern) {
+    return TASK_WORKSPACE_DELEGATED_SUBSYSTEMS.find((entry) => entry.concern === concern)?.owner;
+}
+export const WORKSPACE_RECONCILIATION_STATUSES = [
+    "healthy",
+    "missing",
+    "drifted",
+    "locked",
+    "partially-created",
+    "stale-pointer",
+    "unmanaged-path",
+    "recovery-required",
+];
+export function isWorkspaceReconciliationStatus(value) {
+    return (typeof value === "string" &&
+        WORKSPACE_RECONCILIATION_STATUSES.includes(value));
+}
+// Lifecycle states past the operational window: a missing worktree for one of these is EXPECTED
+// (cleanup), so reconciliation treats them as settled rather than drifted.
+const TERMINAL_LIFECYCLE_STATES = [
+    "merged",
+    "archived",
+    "abandoned",
+    "cleanup-pending",
+];
+const PARTIAL_LIFECYCLE_STATES = [
+    "provisioning",
+    "failed",
+];
+// The single authoritative map from a drift marker to its recovery strategy + whether an operator
+// must act (e.g. a moved HEAD or uncommitted work may carry intentional changes, and a containment
+// escape is never auto-repaired). Consumed by both reconciliation and the repair service (AC5).
+const DRIFT_MARKER_RECOVERY = {
+    "worktree-missing": { strategy: "recreate-worktree", operatorActionRequired: false },
+    // A moved-but-readable gitdir can be re-linked automatically (the pointer identity is re-derived);
+    // a missing/corrupt `.git` pointer cannot be repaired by the narrow worktree adapter without risking
+    // loss of the worktree's uncommitted work, so it is operator-guided.
+    "gitdir-mismatch": { strategy: "reconcile-pointer", operatorActionRequired: false },
+    "pointer-stale": { strategy: "operator-repair", operatorActionRequired: true },
+    "head-moved": { strategy: "operator-repair", operatorActionRequired: true },
+    // A deleted local branch cannot be safely re-created by the narrow worktree adapter without risking
+    // loss of the worktree's commits, so reattachment is operator-guided, never automatic.
+    "branch-deleted": { strategy: "reattach-branch", operatorActionRequired: true },
+    "uncommitted-changes": { strategy: "commit-or-stash-required", operatorActionRequired: true },
+    "lock-stale": { strategy: "release-stale-lock", operatorActionRequired: false },
+    "path-escape": { strategy: "operator-repair", operatorActionRequired: true },
+};
+// Pure: map a set of drift markers to ordered, de-duplicated recovery hints. The order follows the
+// input marker order so the most salient drift drives the first suggested repair.
+export function planWorkspaceRecoveryHints(driftMarkers) {
+    const hints = [];
+    const seen = new Set();
+    for (const marker of driftMarkers) {
+        if (!isTaskWorkspaceDriftMarker(marker) || seen.has(marker))
+            continue;
+        seen.add(marker);
+        const mapping = DRIFT_MARKER_RECOVERY[marker];
+        hints.push({
+            marker,
+            strategy: mapping.strategy,
+            operatorActionRequired: mapping.operatorActionRequired,
+        });
+    }
+    return hints;
+}
+function withStaleLock(markers, facts) {
+    return facts.lockPresent && !facts.lockLive ? [...markers, "lock-stale"] : markers;
+}
+function outcome(status, markers) {
+    return { status, driftMarkers: markers, recoveryHints: planWorkspaceRecoveryHints(markers) };
+}
+// Pure deterministic classifier with a fixed precedence (most severe first): a containment escape and
+// a live foreign lock short-circuit before any disk classification; terminal lifecycles are settled;
+// then partial-creation, then on-disk drift (missing → stale pointer → branch/HEAD/dirty), then a
+// lingering recovery-required flag, then a stale lock on an otherwise-healthy workspace.
+// eslint-disable-next-line complexity
+export function classifyWorkspaceReconciliation(facts) {
+    if (!facts.pathContained)
+        return outcome("unmanaged-path", ["path-escape"]);
+    if (facts.lockedByOtherActor)
+        return outcome("locked", []);
+    if (TERMINAL_LIFECYCLE_STATES.includes(facts.lifecycleState))
+        return outcome("healthy", []);
+    if (PARTIAL_LIFECYCLE_STATES.includes(facts.lifecycleState)) {
+        const base = !facts.worktreeDirExists
+            ? ["worktree-missing"]
+            : !facts.gitPointerPresent
+                ? ["pointer-stale"]
+                : [];
+        return outcome("partially-created", withStaleLock(base, facts));
+    }
+    if (!facts.worktreeDirExists)
+        return outcome("missing", withStaleLock(["worktree-missing"], facts));
+    if (!facts.gitPointerPresent)
+        return outcome("stale-pointer", withStaleLock(["pointer-stale"], facts));
+    if (!facts.gitdirIdentityMatches) {
+        return outcome("stale-pointer", withStaleLock(["gitdir-mismatch"], facts));
+    }
+    if (!facts.taskBranchPresent)
+        return outcome("drifted", withStaleLock(["branch-deleted"], facts));
+    if (!facts.headMatches)
+        return outcome("drifted", withStaleLock(["head-moved"], facts));
+    if (facts.uncommittedChanges) {
+        return outcome("drifted", withStaleLock(["uncommitted-changes"], facts));
+    }
+    if (facts.lifecycleState === "recovery-required") {
+        return outcome("recovery-required", withStaleLock([], facts));
+    }
+    if (facts.lockPresent && !facts.lockLive)
+        return outcome("drifted", ["lock-stale"]);
+    return outcome("healthy", []);
+}
+// Pure: the health enum value reconciliation persists for a given status, so the stored health stays
+// consistent with the classification (and #448 can read either).
+export function reconciliationHealth(status) {
+    switch (status) {
+        case "healthy":
+            return "healthy";
+        case "missing":
+            return "missing";
+        case "drifted":
+        case "stale-pointer":
+            return "drifted";
+        case "locked":
+            return "locked-out";
+        case "partially-created":
+        case "unmanaged-path":
+        case "recovery-required":
+            return "degraded";
+        default:
+            return "unknown";
+    }
+}
+// Pure: whether reconciliation should flag a once-operational workspace (active/paused/handoff-ready)
+// as recovery-required because its worktree is GONE or structurally unusable (missing, a broken/moved
+// git pointer, or an escaped path). A merely `drifted` workspace (moved HEAD, uncommitted work, branch
+// mismatch, stale lock) keeps a usable worktree, so it is surfaced via health + drift markers + hints
+// WITHOUT being forced out of its lifecycle — crisp classification over aggressive auto-healing. A
+// partially-created (provisioning/failed) workspace is left to the provisioning retry path, and a live
+// foreign lock is deferred, never flagged.
+export function reconciliationRequiresRecoveryFlag(status, lifecycleState) {
+    if (lifecycleState !== "active" &&
+        lifecycleState !== "paused" &&
+        lifecycleState !== "handoff-ready") {
+        return false;
+    }
+    return status === "missing" || status === "stale-pointer" || status === "unmanaged-path";
+}
+// Pure: reconstruct the reconciliation status from the CONTENT-FREE persisted instance fields, so a
+// read-only report can be derived without re-running IO (the GET surface) and matches what a live
+// reconcile last persisted. Mirrors the precedence of classifyWorkspaceReconciliation.
+// eslint-disable-next-line complexity
+export function reconciliationStatusFromInstance(input) {
+    const markers = input.driftMarkers;
+    if (markers.includes("path-escape"))
+        return "unmanaged-path";
+    if (input.health === "locked-out")
+        return "locked";
+    if (TERMINAL_LIFECYCLE_STATES.includes(input.lifecycleState))
+        return "healthy";
+    if (PARTIAL_LIFECYCLE_STATES.includes(input.lifecycleState))
+        return "partially-created";
+    if (markers.includes("worktree-missing"))
+        return "missing";
+    if (markers.includes("pointer-stale") || markers.includes("gitdir-mismatch")) {
+        return "stale-pointer";
+    }
+    if (markers.includes("branch-deleted") ||
+        markers.includes("head-moved") ||
+        markers.includes("uncommitted-changes") ||
+        markers.includes("lock-stale")) {
+        return "drifted";
+    }
+    if (input.lifecycleState === "recovery-required")
+        return "recovery-required";
+    return "healthy";
+}
+// ─── Repair applicability (Issue #447) ──────────────────────────────────────────────
+// A repair may only apply a strategy the reconciliation actually recommended for the workspace, so a
+// caller cannot drive an arbitrary git mutation: the repair service validates the requested strategy
+// against the instance's current recovery hints. `abandon-and-cleanup` is the one universal escape
+// (always available for a non-healthy workspace) and `operator-repair`/`commit-or-stash-required`
+// signal that no automatic mutation is safe — the operator must act first.
+// The strategies the repair service can apply WITHOUT operator action, because each is reversible /
+// non-destructive: recreate a missing worktree from the still-present branch, refresh a stale/moved
+// worktree pointer, or release an expired lock. `reattach-branch`, `operator-repair`, and
+// `commit-or-stash-required` are deliberately excluded — they require a human decision.
+export function isAutomaticWorkspaceRepairStrategy(strategy) {
+    return (strategy === "reconcile-pointer" ||
+        strategy === "recreate-worktree" ||
+        strategy === "release-stale-lock");
+}
+// Pure: whether `strategy` is applicable given the recovery hints reconciliation produced. An
+// automatic strategy is applicable iff a hint recommends it; `abandon-and-cleanup` is applicable for
+// any non-healthy status; operator strategies are never "applicable" as an automatic repair.
+export function isWorkspaceRepairStrategyApplicable(input) {
+    if (input.strategy === "abandon-and-cleanup")
+        return input.status !== "healthy";
+    if (!isAutomaticWorkspaceRepairStrategy(input.strategy))
+        return false;
+    return input.recoveryHints.some((hint) => hint.strategy === input.strategy && !hint.operatorActionRequired);
+}
+export const WORKSPACE_RECONCILIATION_ENTRY_ALLOWED_KEYS = [
+    "schemaVersion",
+    "workspaceId",
+    "taskId",
+    "status",
+    "lifecycleState",
+    "health",
+    "driftMarkers",
+    "recoveryHints",
+    "repairable",
+    "operatorActionRequired",
+    "lastVerifiedAt",
+];
+// Pure: the two derived booleans on a reconciliation entry. `repairable` is true when an automatic
+// strategy is available OR the workspace is partially-created (the canonical retry case, AC3).
+export function workspaceEntryRepairable(input) {
+    if (input.status === "partially-created")
+        return true;
+    return input.recoveryHints.some((hint) => !hint.operatorActionRequired);
+}
+export function workspaceEntryOperatorActionRequired(recoveryHints) {
+    return recoveryHints.some((hint) => hint.operatorActionRequired);
+}
+// Pure: build a content-free reconciliation entry from the persisted (content-free) instance fields.
+// The status is reconstructed from those fields so a read-only report matches what a live reconcile
+// last persisted, and the two derived booleans come from the recovery hints. Used by both the live and
+// stored-derived report paths so they cannot diverge (AC5).
+export function deriveReconciliationEntry(input) {
+    const status = reconciliationStatusFromInstance({
+        lifecycleState: input.lifecycleState,
+        health: input.health,
+        driftMarkers: input.driftMarkers,
+    });
+    return {
+        schemaVersion: TASK_WORKSPACE_SCHEMA_VERSION,
+        workspaceId: input.workspaceId,
+        taskId: input.taskId,
+        status,
+        lifecycleState: input.lifecycleState,
+        health: input.health,
+        driftMarkers: input.driftMarkers,
+        recoveryHints: input.recoveryHints,
+        repairable: workspaceEntryRepairable({ status, recoveryHints: input.recoveryHints }),
+        operatorActionRequired: workspaceEntryOperatorActionRequired(input.recoveryHints),
+        ...(input.lastVerifiedAt !== undefined ? { lastVerifiedAt: input.lastVerifiedAt } : {}),
+    };
+}
+// eslint-disable-next-line complexity
+export function validateWorkspaceReconciliationEntry(input) {
+    if (!isRecord(input))
+        return { ok: false, reasons: ["entry must be an object"] };
+    const reasons = unknownKeyReasons(input, WORKSPACE_RECONCILIATION_ENTRY_ALLOWED_KEYS);
+    if (input.schemaVersion !== TASK_WORKSPACE_SCHEMA_VERSION)
+        reasons.push("schemaVersion invalid");
+    for (const key of ["workspaceId", "taskId"]) {
+        if (!isNonEmptyString(input[key]))
+            reasons.push(`${key} must be a non-empty string`);
+    }
+    if (!isWorkspaceReconciliationStatus(input.status))
+        reasons.push("status invalid");
+    if (!isTaskWorkspaceLifecycleState(input.lifecycleState))
+        reasons.push("lifecycleState invalid");
+    if (!isTaskWorkspaceHealth(input.health))
+        reasons.push("health invalid");
+    if (!Array.isArray(input.driftMarkers) || !input.driftMarkers.every(isTaskWorkspaceDriftMarker)) {
+        reasons.push("driftMarkers must be an array of valid markers");
+    }
+    validateRecoveryHints(input.recoveryHints, reasons);
+    if (!isBoolean(input.repairable))
+        reasons.push("repairable must be a boolean");
+    if (!isBoolean(input.operatorActionRequired)) {
+        reasons.push("operatorActionRequired must be a boolean");
+    }
+    if (input.lastVerifiedAt !== undefined && !isNonEmptyString(input.lastVerifiedAt)) {
+        reasons.push("lastVerifiedAt must be a non-empty string when present");
+    }
+    return reasons.length === 0 ? { ok: true } : { ok: false, reasons };
+}
+export const WORKSPACE_ACTIVE_RESTORATION_KINDS = [
+    "none",
+    "restored",
+    "recovery-required",
+    "cleared-dangling",
+    "ambiguous",
+];
+export function isWorkspaceActiveRestorationKind(value) {
+    return (typeof value === "string" &&
+        WORKSPACE_ACTIVE_RESTORATION_KINDS.includes(value));
+}
+// Pure: decide how (and whether) to restore the active workspace after restart, given the persisted
+// pointer target (or undefined for unbound mode) and the reconciliation entries. Deterministic and
+// conservative — it never auto-selects among ambiguous active workspaces.
+export function resolveActiveRestoration(pointerWorkspaceId, entries) {
+    if (pointerWorkspaceId === undefined || pointerWorkspaceId.length === 0) {
+        const activeIds = entries
+            .filter((entry) => entry.lifecycleState === "active")
+            .map((entry) => entry.workspaceId)
+            .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+        if (activeIds.length >= 2)
+            return { kind: "ambiguous", ambiguousWorkspaceIds: activeIds };
+        return { kind: "none" };
+    }
+    const target = entries.find((entry) => entry.workspaceId === pointerWorkspaceId);
+    if (target === undefined)
+        return { kind: "cleared-dangling", workspaceId: pointerWorkspaceId };
+    if (target.status === "healthy")
+        return { kind: "restored", workspaceId: pointerWorkspaceId };
+    return { kind: "recovery-required", workspaceId: pointerWorkspaceId };
+}
+export function validateWorkspaceActiveRestoration(input) {
+    if (!isRecord(input))
+        return { ok: false, reasons: ["restoration must be an object"] };
+    const reasons = unknownKeyReasons(input, [
+        "kind",
+        "workspaceId",
+        "ambiguousWorkspaceIds",
+    ]);
+    if (!isWorkspaceActiveRestorationKind(input.kind))
+        reasons.push("kind invalid");
+    if (input.workspaceId !== undefined && !isNonEmptyString(input.workspaceId)) {
+        reasons.push("workspaceId must be a non-empty string when present");
+    }
+    if (input.ambiguousWorkspaceIds !== undefined) {
+        if (!Array.isArray(input.ambiguousWorkspaceIds) ||
+            !input.ambiguousWorkspaceIds.every(isNonEmptyString)) {
+            reasons.push("ambiguousWorkspaceIds must be an array of non-empty strings when present");
+        }
+    }
+    return reasons.length === 0 ? { ok: true } : { ok: false, reasons };
+}
+export const WORKSPACE_RECONCILIATION_REPORT_ALLOWED_KEYS = [
+    "schemaVersion",
+    "generatedAt",
+    "entries",
+    "activeRestoration",
+];
+export function validateWorkspaceReconciliationReport(input) {
+    if (!isRecord(input))
+        return { ok: false, reasons: ["report must be an object"] };
+    const reasons = unknownKeyReasons(input, WORKSPACE_RECONCILIATION_REPORT_ALLOWED_KEYS);
+    if (input.schemaVersion !== TASK_WORKSPACE_SCHEMA_VERSION)
+        reasons.push("schemaVersion invalid");
+    if (!isNonEmptyString(input.generatedAt))
+        reasons.push("generatedAt must be a non-empty string");
+    if (!Array.isArray(input.entries))
+        reasons.push("entries must be an array");
+    else {
+        input.entries.forEach((entry, index) => {
+            const entryValidation = validateWorkspaceReconciliationEntry(entry);
+            if (!entryValidation.ok) {
+                reasons.push(`entries[${String(index)}]: ${entryValidation.reasons.join("; ")}`);
+            }
+        });
+    }
+    const restorationValidation = validateWorkspaceActiveRestoration(input.activeRestoration);
+    if (!restorationValidation.ok) {
+        reasons.push(`activeRestoration: ${restorationValidation.reasons.join("; ")}`);
+    }
+    return reasons.length === 0 ? { ok: true } : { ok: false, reasons };
+}
+export const WORKSPACE_HEALTH_CLASSIFICATIONS = [
+    "healthy",
+    "dirty",
+    "drifted",
+    "missing",
+    "stale-pointer",
+    "locked",
+    "orphaned",
+    "archived",
+    "cleanup-ready",
+    "recovery-required",
+];
+export function isWorkspaceHealthClassification(value) {
+    return (typeof value === "string" &&
+        WORKSPACE_HEALTH_CLASSIFICATIONS.includes(value));
+}
+// The lifecycle states from which a workspace may be physically cleaned up. STRICTER than the contract
+// transition table (which permits `active->cleanup-pending` with operator approval): #448 policy
+// requires a workspace be SETTLED (archived/merged/abandoned/failed) or already cleanup-pending before
+// its worktree can be removed, so an active/paused/handoff-ready/recovery-required workspace can never
+// be cleaned without first transitioning it to a settled state (defense in depth, SC4).
+export const WORKSPACE_CLEANUP_ELIGIBLE_LIFECYCLE_STATES = [
+    "archived",
+    "merged",
+    "abandoned",
+    "failed",
+    "cleanup-pending",
+];
+export function isCleanupEligibleLifecycleState(value) {
+    return (isTaskWorkspaceLifecycleState(value) &&
+        WORKSPACE_CLEANUP_ELIGIBLE_LIFECYCLE_STATES.includes(value));
+}
+export const WORKSPACE_CLEANUP_REFUSAL_REASONS = [
+    "ownership-unproven",
+    "path-escape",
+    "lock-live",
+    "worktree-dirty",
+    "not-eligible-state",
+];
+export function isWorkspaceCleanupRefusalReason(value) {
+    return (typeof value === "string" &&
+        WORKSPACE_CLEANUP_REFUSAL_REASONS.includes(value));
+}
+// Pure: the SINGLE cleanup-safety gate, shared by the health classifier (`cleanup-ready`) and the
+// keiko-server cleanup service (refusal), so they can never diverge. Refusal precedence (most
+// fundamental first): ownership must be proven (SC1), the path must be realpath-contained inside the
+// managed root (SC1/SC2), no live lock may be held (SC4), the worktree must be clean (SC4), and a
+// persisted instance must be in a cleanup-eligible lifecycle state. An orphaned worktree (no record)
+// skips the lifecycle check — once owned, contained, clean, and unlocked it is always removable.
+export function evaluateWorkspaceCleanupSafety(facts) {
+    if (!facts.ownershipProven)
+        return { allowed: false, refusalReason: "ownership-unproven" };
+    if (!facts.pathContained)
+        return { allowed: false, refusalReason: "path-escape" };
+    if (facts.lockLive)
+        return { allowed: false, refusalReason: "lock-live" };
+    if (facts.worktreeDirty)
+        return { allowed: false, refusalReason: "worktree-dirty" };
+    if (facts.hasRecord && !isCleanupEligibleLifecycleState(facts.lifecycleState)) {
+        return { allowed: false, refusalReason: "not-eligible-state" };
+    }
+    return { allowed: true };
+}
+// Pure: maps a reconciliation status + lifecycle + live dirty/cleanup signals to the operational health
+// classification. Severe structural conditions win first (they precede any cleanup consideration); a
+// structurally healthy worktree then resolves by lifecycle — settled (archived/merged) → `archived`,
+// settled-for-disposal (abandoned/failed/cleanup-pending) + cleanup-eligible → `cleanup-ready`,
+// otherwise `dirty` when the working tree is dirty, else `healthy`.
+// eslint-disable-next-line complexity
+function healthClassificationFor(status, lifecycleState, worktreeDirty, cleanupEligible) {
+    if (status === "unmanaged-path")
+        return "recovery-required";
+    if (status === "locked")
+        return "locked";
+    if (status === "missing")
+        return "missing";
+    if (status === "stale-pointer")
+        return "stale-pointer";
+    if (status === "drifted")
+        return "drifted";
+    if (status === "partially-created" || status === "recovery-required")
+        return "recovery-required";
+    // status === "healthy": structurally sound (contained, pointer + branch + HEAD verified, no foreign
+    // lock). A `failed`/`provisioning` lifecycle is a partial-creation reconciliation state, so it never
+    // reaches here (it returns "partially-created" above). Resolve the remaining lifecycles by disposition.
+    if (lifecycleState === "archived" || lifecycleState === "merged")
+        return "archived";
+    if ((lifecycleState === "abandoned" || lifecycleState === "cleanup-pending") && cleanupEligible) {
+        return "cleanup-ready";
+    }
+    return worktreeDirty ? "dirty" : "healthy";
+}
+// Pure: classify ONE persisted instance. Delegates the structural classification to the #447
+// reconciliation classifier (no second precedence chain) and the cleanup decision to the single safety
+// gate, then composes them into the operational health evaluation.
+export function classifyWorkspaceHealth(signals) {
+    const facts = signals.reconciliation;
+    const recon = classifyWorkspaceReconciliation(facts);
+    const decision = evaluateWorkspaceCleanupSafety({
+        lifecycleState: facts.lifecycleState,
+        hasRecord: true,
+        pathContained: facts.pathContained,
+        ownershipProven: signals.ownershipProven,
+        worktreeDirty: signals.worktreeDirty,
+        lockLive: facts.lockLive,
+    });
+    return {
+        classification: healthClassificationFor(recon.status, facts.lifecycleState, signals.worktreeDirty, decision.allowed),
+        driftMarkers: recon.driftMarkers,
+        recoveryHints: recon.recoveryHints,
+        cleanupEligible: decision.allowed,
+    };
+}
+export const WORKSPACE_HEALTH_ENTRY_KINDS = [
+    "instance",
+    "orphan-worktree",
+];
+export function isWorkspaceHealthEntryKind(value) {
+    return (typeof value === "string" &&
+        WORKSPACE_HEALTH_ENTRY_KINDS.includes(value));
+}
+export const WORKSPACE_HEALTH_ENTRY_ALLOWED_KEYS = [
+    "schemaVersion",
+    "kind",
+    "classification",
+    "driftMarkers",
+    "recoveryHints",
+    "cleanupEligible",
+    "workspaceId",
+    "taskId",
+    "lifecycleState",
+    "health",
+    "lastVerifiedAt",
+    "orphanId",
+];
+// Pure: build a content-free health entry for a persisted instance from its (content-free) fields plus
+// the pure evaluation. Used by the server health service so the report shape cannot diverge from the
+// classifier output.
+export function deriveWorkspaceHealthEntry(input) {
+    return {
+        schemaVersion: TASK_WORKSPACE_SCHEMA_VERSION,
+        kind: "instance",
+        classification: input.evaluation.classification,
+        driftMarkers: input.evaluation.driftMarkers,
+        recoveryHints: input.evaluation.recoveryHints,
+        cleanupEligible: input.evaluation.cleanupEligible,
+        workspaceId: input.workspaceId,
+        taskId: input.taskId,
+        lifecycleState: input.lifecycleState,
+        health: input.health,
+        ...(input.lastVerifiedAt !== undefined ? { lastVerifiedAt: input.lastVerifiedAt } : {}),
+    };
+}
+// Pure: build a content-free health entry for an orphaned managed worktree (no persisted record). It
+// always classifies `orphaned`; `cleanupEligible` reflects whether the live safety gate cleared it.
+export function deriveOrphanWorktreeHealthEntry(input) {
+    return {
+        schemaVersion: TASK_WORKSPACE_SCHEMA_VERSION,
+        kind: "orphan-worktree",
+        classification: "orphaned",
+        driftMarkers: [],
+        recoveryHints: [],
+        cleanupEligible: input.cleanupEligible,
+        orphanId: input.orphanId,
+    };
+}
+// eslint-disable-next-line complexity
+export function validateWorkspaceHealthEntry(input) {
+    if (!isRecord(input))
+        return { ok: false, reasons: ["entry must be an object"] };
+    const reasons = unknownKeyReasons(input, WORKSPACE_HEALTH_ENTRY_ALLOWED_KEYS);
+    if (input.schemaVersion !== TASK_WORKSPACE_SCHEMA_VERSION)
+        reasons.push("schemaVersion invalid");
+    if (!isWorkspaceHealthEntryKind(input.kind))
+        reasons.push("kind invalid");
+    if (!isWorkspaceHealthClassification(input.classification))
+        reasons.push("classification invalid");
+    if (!Array.isArray(input.driftMarkers) || !input.driftMarkers.every(isTaskWorkspaceDriftMarker)) {
+        reasons.push("driftMarkers must be an array of valid markers");
+    }
+    validateRecoveryHints(input.recoveryHints, reasons);
+    if (!isBoolean(input.cleanupEligible))
+        reasons.push("cleanupEligible must be a boolean");
+    if (input.kind === "instance") {
+        for (const key of ["workspaceId", "taskId"]) {
+            if (!isNonEmptyString(input[key]))
+                reasons.push(`${key} must be a non-empty string`);
+        }
+        if (!isTaskWorkspaceLifecycleState(input.lifecycleState))
+            reasons.push("lifecycleState invalid");
+        if (!isTaskWorkspaceHealth(input.health))
+            reasons.push("health invalid");
+        if (input.orphanId !== undefined)
+            reasons.push("orphanId not allowed for an instance entry");
+    }
+    else if (input.kind === "orphan-worktree") {
+        if (!isNonEmptyString(input.orphanId))
+            reasons.push("orphanId must be a non-empty string");
+        if (input.classification !== "orphaned")
+            reasons.push("orphan entry must classify as orphaned");
+        for (const key of ["workspaceId", "taskId", "lifecycleState", "health"]) {
+            if (input[key] !== undefined)
+                reasons.push(`${key} not allowed for an orphan entry`);
+        }
+    }
+    if (input.lastVerifiedAt !== undefined && !isNonEmptyString(input.lastVerifiedAt)) {
+        reasons.push("lastVerifiedAt must be a non-empty string when present");
+    }
+    return reasons.length === 0 ? { ok: true } : { ok: false, reasons };
+}
+export const WORKSPACE_HEALTH_REPORT_ALLOWED_KEYS = [
+    "schemaVersion",
+    "generatedAt",
+    "entries",
+];
+export function validateWorkspaceHealthReport(input) {
+    if (!isRecord(input))
+        return { ok: false, reasons: ["report must be an object"] };
+    const reasons = unknownKeyReasons(input, WORKSPACE_HEALTH_REPORT_ALLOWED_KEYS);
+    if (input.schemaVersion !== TASK_WORKSPACE_SCHEMA_VERSION)
+        reasons.push("schemaVersion invalid");
+    if (!isNonEmptyString(input.generatedAt))
+        reasons.push("generatedAt must be a non-empty string");
+    if (!Array.isArray(input.entries))
+        reasons.push("entries must be an array");
+    else {
+        input.entries.forEach((entry, index) => {
+            const entryValidation = validateWorkspaceHealthEntry(entry);
+            if (!entryValidation.ok) {
+                reasons.push(`entries[${String(index)}]: ${entryValidation.reasons.join("; ")}`);
+            }
+        });
+    }
+    return reasons.length === 0 ? { ok: true } : { ok: false, reasons };
+}