@zq-silk/yui 0.15.7 → 0.15.8

package/dist/resources/autoResourceGc.js

@@ -98,14 +98,14 @@ function collectTaskStatuses(store) {
     return statuses;
 }
 /**
- * Workspace paths claimed by active durable Jobs. An active Turn still
+ * Workspace paths claimed by active durable Jobs. An active AgentRun still
  * holds its workspace even after the managed workspace record is gone, so
- * those paths stay protected until the Turn finishes.
+ * those paths stay protected until the AgentRun finishes.
  */
 function collectActiveWorkspaceOwnerPaths(store) {
     const paths = [];
     for (const task of store.listTasks()) {
-        for (const run of store.listTurns(task.id)) {
+        for (const run of store.listRuns(task.id)) {
             if (run.status !== "active")
                 continue;
             const workspace = run.workspace;

package/dist/resources/liveReferences.js

@@ -142,7 +142,7 @@ export async function scanLiveReferences(input) {
             }
         }
     }
-    // 6. Active durable workspace owners (e.g. an active Turn launch).
+    // 6. Active durable workspace owners (e.g. an active AgentRun launch).
     const activeOwners = input.ports?.activeWorkspaceOwners !== undefined
         ? input.ports.activeWorkspaceOwners()
         : [];
@@ -232,7 +232,7 @@ function readActiveReleaseClaims(home) {
     }
 }
 /**
- * Read Session owner records (`runtime/session-owners/<runtimeGenerationId>.json`). A
+ * Read Session owner records (`runtime/session-owners/<pid-startIdentity>.json`). A
  * record whose Provider root is physically alive with a matching start
  * identity protects its runtime root. A dead PID is stale (reconciliation
  * removes those records); an identity conflict or unreadable record fails
@@ -301,7 +301,7 @@ function readSessionOwnerClaims(home) {
         if (typeof record.runtimeRoot === "string" && record.runtimeRoot.length > 0) {
             claims.push({
                 path: resolve(record.runtimeRoot),
-                token: `session-owner:${typeof record.runtimeGenerationId === "string" ? record.runtimeGenerationId : entry.name}`
+                token: `session-owner:${pid}-${startIdentity}`
             });
         }
     }

package/dist/resources/projectResource.js

@@ -0,0 +1,123 @@
+import { createHash } from "node:crypto";
+import { isAbsolute, resolve } from "node:path";
+import { requireIdentity, requireText, requireTimestamp } from "../domain/validation.js";
+export function validateExecutionEnvironmentSnapshot(value) {
+    if (!value || typeof value !== "object")
+        throw new Error("Execution environment must be an object.");
+    requireIdentity(value.taskId, "Execution environment Task");
+    requireIdentity(value.preparationId, "Execution environment preparation");
+    if (value.environmentRef !== `${value.taskId}/${value.preparationId}`) {
+        throw new Error("Execution environment reference does not match its preparation.");
+    }
+    if (!["read", "write"].includes(value.access) || value.isolation !== "trusted-local" || !value.directory) {
+        throw new Error("Execution environment requires a trusted-local directory and explicit access.");
+    }
+    requireText(value.directory.path, "Execution environment path");
+    if (!isAbsolute(value.directory.path) || resolve(value.directory.path) !== value.directory.path) {
+        throw new Error("Execution environment path must be absolute and normalized.");
+    }
+    requireText(value.directory.device, "Execution environment device");
+    requireText(value.directory.inode, "Execution environment inode");
+    if (!["preparation", "user"].includes(value.directory.ownership))
+        throw new Error("Invalid execution directory owner.");
+    return value;
+}
+export function contentDigest(content) {
+    return createHash("sha256").update(content, "utf8").digest("hex");
+}
+export function validateArtifact(artifact) {
+    if (artifact.schemaVersion !== 1)
+        throw new Error("Artifact schemaVersion must be 1.");
+    requireIdentity(artifact.id, "Artifact id");
+    requireIdentity(artifact.taskId, "Artifact Task");
+    requireText(artifact.displayName, "Artifact name");
+    requireText(artifact.mediaType, "Artifact media type");
+    requireText(artifact.provenance, "Artifact provenance");
+    requireTimestamp(artifact.createdAt, "Artifact timestamp");
+    if (artifact.kind === "content" || artifact.kind === "receipt") {
+        if (typeof artifact.content !== "string" || Buffer.byteLength(artifact.content) > 8 * 1024 * 1024) {
+            throw new Error("Artifact content must be UTF-8 text of at most 8 MiB.");
+        }
+        if (artifact.digest !== contentDigest(artifact.content))
+            throw new Error("Artifact content digest mismatch.");
+        if (artifact.kind === "receipt") {
+            requireIdentity(artifact.jobId, "Artifact Job");
+            requireText(artifact.receiptRef, "Artifact receipt");
+        }
+    }
+    else if (artifact.kind === "external-version") {
+        requireIdentity(artifact.resourceId, "Artifact resource");
+        requireText(artifact.version, "Artifact external version");
+        requireText(artifact.verification, "Artifact version verification");
+    }
+    else if (artifact.kind === "reference") {
+        requireText(artifact.locator, "Reference locator");
+        requireTimestamp(artifact.observedAt, "Reference observation");
+    }
+    else
+        throw new Error("Unknown Artifact kind.");
+    return artifact;
+}
+export function stableArtifactRef(artifact) {
+    validateArtifact(artifact);
+    if (artifact.kind === "reference")
+        throw new Error("Reference material is not a fixed result.");
+    return { taskId: artifact.taskId, artifactId: artifact.id, kind: artifact.kind,
+        ...("digest" in artifact ? { digest: artifact.digest } : {}) };
+}
+/** Listings expose locators and provenance without replaying every body. */
+export function artifactSummary(artifact) {
+    if ("content" in artifact) {
+        const { content, ...summary } = artifact;
+        return { ...summary, contentBytes: Buffer.byteLength(content, "utf8") };
+    }
+    return artifact;
+}
+export function validateLocalResource(resource) {
+    if (resource.schemaVersion !== 1 || resource.kind !== "local-directory" || resource.ownership !== "user") {
+        throw new Error("Invalid local Resource record.");
+    }
+    requireIdentity(resource.id, "Resource id");
+    requireText(resource.displayName, "Resource name");
+    requireText(resource.path, "Resource path");
+    requireText(resource.device, "Resource device");
+    requireText(resource.inode, "Resource inode");
+    requireTimestamp(resource.createdAt, "Resource timestamp");
+    return resource;
+}
+export function validateEnvironmentPreparation(record) {
+    if (record.schemaVersion !== 1 || !["prepared", "adopted", "released"].includes(record.disposition)) {
+        throw new Error("Invalid Environment preparation.");
+    }
+    requireIdentity(record.id, "Preparation id");
+    requireIdentity(record.taskId, "Preparation Task");
+    requireText(record.intentDigest, "Preparation intent");
+    if (!Array.isArray(record.resourceRefs) || new Set(record.resourceRefs).size !== record.resourceRefs.length) {
+        throw new Error("Preparation resources must be unique.");
+    }
+    record.resourceRefs.forEach((id) => requireIdentity(id, "Preparation resource"));
+    if (!["read", "write"].includes(record.access))
+        throw new Error("Invalid preparation access.");
+    if (!["none", "trusted-local"].includes(record.isolation)
+        || (record.directory === undefined) !== (record.isolation === "none")) {
+        throw new Error("Environment isolation must describe the actual local preparation.");
+    }
+    if ((record.directory === undefined) !== (record.environmentRef === undefined)) {
+        throw new Error("Environment reference requires an actual directory.");
+    }
+    if (record.directory) {
+        requireText(record.directory.path, "Environment path");
+        requireText(record.directory.device, "Environment device");
+        requireText(record.directory.inode, "Environment inode");
+        if (!["preparation", "user"].includes(record.directory.ownership))
+            throw new Error("Invalid directory owner.");
+    }
+    requireTimestamp(record.createdAt, "Preparation timestamp");
+    requireTimestamp(record.updatedAt, "Preparation update");
+    if (record.releaseEvidence !== undefined) {
+        if (record.disposition !== "released")
+            throw new Error("Release evidence requires a released preparation.");
+        requireText(record.releaseEvidence, "Release evidence");
+    }
+    return record;
+}

package/dist/resources/projectResourceService.js

@@ -0,0 +1,421 @@
+import { randomUUID } from "node:crypto";
+import { lstatSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmdirSync, statSync } from "node:fs";
+import { join, relative, resolve, isAbsolute } from "node:path";
+import { checkGrant, recordGrantUse } from "../grant/capabilityGrant.js";
+import { requireIdentity, requireText, requireTimestamp } from "../domain/validation.js";
+import { validateProject } from "../repository/project.js";
+import { updateRole } from "../role/role.js";
+import { saveTaskRoleUpdate } from "../role/taskRoleUpdate.js";
+import { assertRoleRuntimeMutationAllowed } from "../commands/roleRuntimeGuard.js";
+import { assertProviderConversationReplaceable, currentProviderConversation } from "../runtime/providerRuntimeIdentity.js";
+import { projectProviderContinuations } from "../runtime/runtimeContinuationProjection.js";
+import { contentDigest, validateArtifact, stableArtifactRef, validateExecutionEnvironmentSnapshot } from "./projectResource.js";
+export function validateArtifactInput(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Artifact input must be an object.");
+    const input = value;
+    requireText(input.displayName, "Artifact name");
+    requireText(input.provenance, "Artifact provenance");
+    if (input.mediaType !== undefined)
+        requireText(input.mediaType, "Artifact media type");
+    switch (input.kind) {
+        case "content":
+            if (typeof input.content !== "string" || Buffer.byteLength(input.content) > 8 * 1024 * 1024) {
+                throw new Error("Artifact content must be UTF-8 text of at most 8 MiB.");
+            }
+            break;
+        case "receipt":
+            requireIdentity(input.jobId, "Artifact Job");
+            requireText(input.receiptRef, "Artifact receipt");
+            break;
+        case "external-version":
+            requireIdentity(input.resourceId, "Artifact resource");
+            requireText(input.version, "Artifact external version");
+            requireText(input.verification, "Artifact version verification");
+            break;
+        case "reference":
+            requireText(input.locator, "Reference locator");
+            requireTimestamp(input.observedAt, "Reference observation");
+            break;
+        default: throw new Error("Unknown Artifact kind.");
+    }
+    return input;
+}
+/** Trusted typed owner; the public caller is authenticated by the existing
+ * capability boundary. No new Store, worker, scheduling or Git authority. */
+export function createProjectResources(store, now = () => new Date()) {
+    const task = (taskId) => {
+        const value = store.getTask(taskId);
+        if (!value)
+            throw new Error(`Task not found: ${taskId}.`);
+        return value;
+    };
+    const intent = (taskId) => {
+        const value = task(taskId);
+        return contentDigest(JSON.stringify({
+            // Git's moving delivery pointers do not change Resource intent.
+            projectBindings: value.projectBindings.map(({ projectId, directory, baseRef }) => ({ projectId, directory, baseRef })),
+            projects: value.projectBindings.map(({ projectId }) => {
+                const project = store.getProject(projectId);
+                return { projectId, resources: project?.resourceRefs, providers: project?.defaultCapabilityProviders };
+            })
+        }));
+    };
+    const openTask = (taskId) => {
+        const value = task(taskId);
+        if (value.status !== "draft" && value.status !== "active")
+            throw new Error("Task is not open for environment adoption.");
+        return value;
+    };
+    const resource = (resourceId) => {
+        const value = store.getLocalResource(resourceId);
+        if (!value)
+            throw new Error(`Local resource not found: ${resourceId}.`);
+        return value;
+    };
+    const grantFor = (taskId, resourceId, access, reservation, reservedOnly = false) => {
+        const target = resource(resourceId);
+        const grant = store.listCapabilityGrants(taskId).find((candidate) => {
+            // A Project scope is visibility, not an exhaustive Resource grant. A
+            // concrete resource bound is mandatory even for a broadly named action.
+            if (!candidate.parameterBounds.resourceId?.includes(resourceId))
+                return false;
+            if (reservedOnly && (reservation === undefined || !candidate.useReservations.includes(reservation)))
+                return false;
+            if (candidate.scope.homePath !== undefined && resolve(candidate.scope.homePath) !== target.path)
+                return false;
+            if (candidate.scope.projectIds?.some((id) => !task(taskId).projectBindings.some((binding) => binding.projectId === id)))
+                return false;
+            return checkGrant(candidate, { action: `resource.local.${access}`, params: { resourceId } }, now(), { skipUsesCheck: reservation !== undefined && candidate.useReservations.includes(reservation) }).allowed;
+        });
+        if (!grant)
+            throw new Error(`Resource grant unavailable: ${resourceId}/${access}.`);
+        return grant;
+    };
+    const preparation = (taskId, id) => {
+        const value = store.getEnvironmentPreparation(taskId, id);
+        if (!value)
+            throw new Error(`Environment preparation not found: ${taskId}/${id}.`);
+        return value;
+    };
+    const assertLocalWriteOwner = (path, access) => {
+        if (access !== "write")
+            return;
+        const protectedPaths = [
+            realpathSync(store.rootDirectory()),
+            ...store.listProjects().map((project) => project.path),
+            ...store.listTasks().flatMap((value) => store.listManagedWorkspaces(value.id)
+                .flatMap((workspace) => [workspace.root, ...workspace.entries.map((entry) => entry.path)]))
+        ];
+        if (protectedPaths.some((protectedPath) => overlaps(path, currentOrAbsentPath(protectedPath)))) {
+            throw new Error("Local resource overlaps a Yui Home or managed Git workspace; use its existing owner and Git operations.");
+        }
+    };
+    const resolveExecutionEnvironment = (taskId, id) => {
+        openTask(taskId);
+        const value = preparation(taskId, id);
+        if (value.disposition !== "adopted")
+            throw new Error("Execution environment must be adopted and not released.");
+        if (value.intentDigest !== intent(taskId))
+            throw new Error("Task resource/configuration intent changed; prepare again.");
+        if (!value.directory || !value.environmentRef || value.isolation !== "trusted-local") {
+            throw new Error("Empty preparation has no native execution directory; select a directory environment or managed workspace.");
+        }
+        assertDirectory(value.directory);
+        if (value.directory.ownership === "user")
+            assertLocalWriteOwner(value.directory.path, value.access);
+        for (const resourceId of value.resourceRefs) {
+            // Adoption already charged the bounded grant. Launch/resume may recheck
+            // that reservation, but must neither invent nor consume another use.
+            grantFor(taskId, resourceId, value.access, id, true);
+            const target = resource(resourceId);
+            assertDirectory(target);
+            if (target.path !== value.directory.path || target.device !== value.directory.device || target.inode !== value.directory.inode) {
+                throw new Error("Execution environment no longer matches its registered Resource.");
+            }
+        }
+        return validateExecutionEnvironmentSnapshot({
+            taskId, preparationId: id, environmentRef: value.environmentRef,
+            access: value.access, isolation: value.isolation, directory: { ...value.directory }
+        });
+    };
+    return {
+        resolveExecutionEnvironment,
+        bindEnvironment(taskId, roleName, preparationId, source = { source: "environment.bind" }) {
+            return store.transaction((tx) => {
+                openTask(taskId);
+                const role = tx.getRole(taskId, roleName);
+                if (!role)
+                    throw new Error(`Role not found: ${taskId}/${roleName}.`);
+                assertRoleRuntimeMutationAllowed(tx, { scope: "task", taskId, roleName }, "environment binding");
+                const executionEnvironment = preparationId === null ? null : resolveExecutionEnvironment(taskId, preparationId);
+                const timestamp = now();
+                const updated = updateRole(role, { executionEnvironment }, timestamp);
+                // Desired configuration only: active native Sessions retain their
+                // immutable actual snapshot until explicitly ended.
+                saveTaskRoleUpdate(tx, role, updated, timestamp, source);
+                return updated;
+            });
+        },
+        saveArtifact(taskId, input) {
+            task(taskId);
+            validateArtifactInput(input);
+            const base = { schemaVersion: 1, taskId, id: `artifact-${randomUUID()}`,
+                displayName: input.displayName, mediaType: input.mediaType ?? "text/plain",
+                provenance: input.provenance, createdAt: now().toISOString() };
+            let artifact;
+            if (input.kind === "content") {
+                artifact = { ...base, kind: input.kind, content: input.content, digest: contentDigest(input.content) };
+            }
+            else if (input.kind === "receipt") {
+                const job = store.getDurableJob(taskId, input.jobId);
+                if (!job?.operation.receiptRefs.includes(input.receiptRef))
+                    throw new Error("Receipt is not recorded by this Task's Job.");
+                const path = realpathSync(input.receiptRef);
+                if (!within(realpathSync(job.artifactsLocator), path))
+                    throw new Error("Receipt is outside the Job artifact directory.");
+                const content = readText(path);
+                artifact = { ...base, kind: input.kind, jobId: job.id, receiptRef: input.receiptRef,
+                    content, digest: contentDigest(content) };
+            }
+            else if (input.kind === "external-version") {
+                // Recording supplied version evidence is not an external resource read.
+                // Actual resource operations must separately pass their owner's grant.
+                artifact = { ...base, kind: input.kind, resourceId: input.resourceId,
+                    version: input.version, verification: input.verification };
+            }
+            else {
+                artifact = { ...base, kind: input.kind, locator: input.locator, observedAt: input.observedAt };
+            }
+            store.saveArtifact(validateArtifact(artifact));
+            return artifact;
+        },
+        resultRefs(taskId, artifactIds) {
+            return artifactIds.map((id) => {
+                const artifact = store.getArtifact(taskId, id);
+                if (!artifact)
+                    throw new Error(`Artifact not found: ${taskId}/${id}.`);
+                return stableArtifactRef(artifact);
+            });
+        },
+        gitResult(taskId, changeSetId) {
+            const changeSet = store.getChangeSet(taskId, changeSetId);
+            if (!changeSet)
+                throw new Error("ChangeSet not found in this Task.");
+            return {
+                kind: "external-version", resourceId: changeSet.projectId,
+                version: changeSet.headCommit,
+                verification: { taskId, changeSetId: changeSet.id, baseCommit: changeSet.baseCommit },
+                // This is a projection of the existing fixed Git result, not another
+                // mutable repository/worktree/Integration record.
+                changeSet
+            };
+        },
+        registerLocalDirectory(displayName, path) {
+            const identity = directoryIdentity(path);
+            return store.transaction((tx) => {
+                const existing = tx.listLocalResources().find((value) => value.device === identity.device && value.inode === identity.inode);
+                if (existing)
+                    return existing;
+                const value = { schemaVersion: 1, id: `resource-${randomUUID()}`,
+                    kind: "local-directory", displayName: requireText(displayName, "Resource name"),
+                    ...identity, ownership: "user", createdAt: now().toISOString() };
+                tx.saveLocalResource(value);
+                return value;
+            });
+        },
+        readLocalResource(taskId, resourceId) {
+            grantFor(taskId, resourceId, "read");
+            return resource(resourceId);
+        },
+        projectContext(taskId, projectId) {
+            if (!task(taskId).projectBindings.some((binding) => binding.projectId === projectId))
+                throw new Error("Project is outside the Task context.");
+            const project = store.getProject(projectId);
+            if (!project)
+                throw new Error("Project not found.");
+            return { id: project.id, name: project.name, knowledge: project.knowledge,
+                resourceRefs: project.resourceRefs, defaultCapabilityProviders: project.defaultCapabilityProviders };
+        },
+        configureProject(projectId, resourceRefs, defaultCapabilityProviders) {
+            return store.transaction((tx) => {
+                const project = tx.getProject(projectId);
+                if (!project || project.status !== "active")
+                    throw new Error("Active Project not found.");
+                resourceRefs.forEach(resource);
+                const next = validateProject({ ...project, resourceRefs, defaultCapabilityProviders, updatedAt: now().toISOString() });
+                tx.saveProject(next);
+                return next;
+            });
+        },
+        prepare(taskId, plan) {
+            openTask(taskId);
+            let directory;
+            const id = `preparation-${randomUUID()}`;
+            const access = plan.kind === "local" ? plan.access : "write";
+            const resourceRefs = plan.kind === "local" ? [plan.resourceId] : [];
+            if (plan.kind === "local") {
+                grantFor(taskId, plan.resourceId, access);
+                const target = resource(plan.resourceId);
+                assertDirectory(target);
+                assertLocalWriteOwner(target.path, access);
+                directory = { path: target.path, device: target.device, inode: target.inode, ownership: "user" };
+            }
+            else if (plan.kind === "scratch") {
+                const parent = join(store.rootDirectory(), "environments");
+                mkdirSync(parent, { recursive: true, mode: 0o700 });
+                if (realpathSync(parent) !== resolve(parent))
+                    throw new Error("Environment root must not be a symlink.");
+                directory = { ...directoryIdentity(mkdtempSync(join(parent, `${id}-`))), ownership: "preparation" };
+            }
+            try {
+                return store.transaction((tx) => {
+                    openTask(taskId);
+                    const timestamp = now().toISOString();
+                    const value = { schemaVersion: 1, id, taskId,
+                        disposition: "prepared", intentDigest: intent(taskId), resourceRefs, access,
+                        isolation: directory ? "trusted-local" : "none",
+                        ...(directory ? { directory, environmentRef: `${taskId}/${id}` } : {}),
+                        createdAt: timestamp, updatedAt: timestamp };
+                    tx.saveEnvironmentPreparation(value);
+                    return value;
+                });
+            }
+            catch (error) {
+                if (directory?.ownership === "preparation") {
+                    // Only the exact newly-created empty directory is eligible. Never
+                    // recursively remove a partial/unknown external preparation.
+                    try {
+                        assertDirectory(directory);
+                        rmdirSync(directory.path);
+                    }
+                    catch (cleanup) {
+                        throw new AggregateError([error, cleanup], `Unadopted environment retained: ${directory.path}`);
+                    }
+                }
+                throw error;
+            }
+        },
+        adopt(taskId, id) {
+            return store.transaction((tx) => {
+                openTask(taskId);
+                const value = preparation(taskId, id);
+                if (value.disposition === "released")
+                    throw new Error("Environment was released.");
+                if (value.intentDigest !== intent(taskId))
+                    throw new Error("Task resource/configuration intent changed; prepare again.");
+                if (value.directory)
+                    assertDirectory(value.directory);
+                if (value.directory?.ownership === "user")
+                    assertLocalWriteOwner(value.directory.path, value.access);
+                const grants = value.resourceRefs.map((resourceId) => grantFor(taskId, resourceId, value.access, id));
+                if (value.disposition === "adopted")
+                    return value;
+                if (value.directory) {
+                    for (const otherTask of tx.listTasks()) {
+                        const conflict = tx.listEnvironmentPreparations(otherTask.id).some((other) => other.disposition === "adopted" && other.directory
+                            && (value.access === "write" || other.access === "write")
+                            && overlaps(other.directory.path, value.directory.path));
+                        if (conflict)
+                            throw new Error("Resource conflicts with an adopted environment; inspect its use or choose isolated scratch.");
+                    }
+                }
+                grants.forEach((grant) => tx.saveCapabilityGrant(taskId, recordGrantUse(grant, now(), id)));
+                const adopted = { ...value, disposition: "adopted", updatedAt: now().toISOString() };
+                tx.saveEnvironmentPreparation(adopted);
+                return adopted;
+            });
+        },
+        release(taskId, id, evidence) {
+            return store.transaction((tx) => {
+                const value = preparation(taskId, id);
+                if (value.disposition === "released")
+                    return value;
+                if (value.disposition === "adopted" && value.directory) {
+                    requireText(evidence?.quiescence ?? "", "Actual quiescence evidence");
+                    const references = (environment) => environment?.taskId === taskId && environment.preparationId === id;
+                    const sessionSets = tx.listRoleSessionSets(taskId);
+                    const continuations = projectProviderContinuations(tx.listEvents(taskId));
+                    for (const set of sessionSets) {
+                        const users = [...Object.values(set.sessions), ...(set.history ?? [])]
+                            .filter((session) => references(session.effective.executionEnvironment));
+                        if (set.providerBinding != null && users.some((session) => session.nativeSessionId === currentProviderConversation(set.providerBinding).conversationId)) {
+                            // A dead Host cannot prove that the native daemon accepted
+                            // nothing or that a detached input has finished.
+                            assertProviderConversationReplaceable(set.providerBinding);
+                        }
+                        if (continuations.some((continuation) => continuation.roleName === set.owner.roleName
+                            && (continuation.execution !== "quiescent"
+                                || continuation.observation !== "exact" || continuation.identityConflict)
+                            && (users.some((session) => session.agentId === continuation.identity.accountScope
+                                && session.nativeSessionId === continuation.identity.conversationId)
+                                || references(tx.getRun(taskId, continuation.runId)?.effective.executionEnvironment)))) {
+                            throw new Error("Environment still has a live or unknown native continuation.");
+                        }
+                    }
+                    if (value.directory && (tx.listRuns(taskId).some((run) => run.status === "active"
+                        && (references(run.effective.executionEnvironment)
+                            || (run.workspace && overlaps(run.workspace.root, value.directory.path))))
+                        || sessionSets.some((set) => [...Object.values(set.sessions), ...(set.history ?? [])].some((session) => session.status === "active" && references(session.effective.executionEnvironment)))
+                        || tx.listDurableJobs(taskId).some((job) => ["queued", "running", "unknown-needs-attention"].includes(job.status)
+                            && overlaps(job.workspace, value.directory.path))))
+                        throw new Error("Environment still has a live or unknown execution reference.");
+                }
+                if (value.directory?.ownership === "preparation") {
+                    assertDirectory(value.directory);
+                    const parent = realpathSync(join(store.rootDirectory(), "environments"));
+                    if (!within(parent, value.directory.path) || !value.directory.path.startsWith(join(parent, `${id}-`))) {
+                        throw new Error("Preparation directory is outside its owned root.");
+                    }
+                    // Content must first be saved or explicitly handled by its owner.
+                    // Nonempty directories are retained with ENOTEMPTY, never force-deleted.
+                    rmdirSync(value.directory.path);
+                }
+                const released = { ...value, disposition: "released", updatedAt: now().toISOString(),
+                    ...(evidence === undefined ? {} : { releaseEvidence: requireText(evidence.quiescence, "Actual quiescence evidence") }) };
+                tx.saveEnvironmentPreparation(released);
+                return released;
+            });
+        }
+    };
+}
+function directoryIdentity(path) {
+    const canonical = realpathSync(resolve(path));
+    const stat = statSync(canonical, { bigint: true });
+    if (!stat.isDirectory())
+        throw new Error("Resource must be a local directory.");
+    return { path: canonical, device: String(stat.dev), inode: String(stat.ino) };
+}
+function assertDirectory(expected) {
+    if (lstatSync(expected.path).isSymbolicLink())
+        throw new Error("Directory identity changed to a symlink.");
+    const current = directoryIdentity(expected.path);
+    if (current.path !== expected.path || current.device !== expected.device || current.inode !== expected.inode) {
+        throw new Error("Directory identity changed; retained for owner inspection.");
+    }
+}
+function within(parent, path) {
+    const value = relative(parent, path);
+    return value !== "" && value !== ".." && !value.startsWith("../") && !isAbsolute(value);
+}
+function overlaps(left, right) {
+    return left === right || within(left, right) || within(right, left);
+}
+function currentOrAbsentPath(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch (error) {
+        // Historical workspace references may outlive a removed directory. Retain
+        // that exact address; never manufacture a replacement or ignore other errors.
+        if (error.code === "ENOENT")
+            return resolve(path);
+        throw error;
+    }
+}
+function readText(path) {
+    const stat = statSync(path);
+    if (!stat.isFile() || stat.size > 8 * 1024 * 1024)
+        throw new Error("Receipt must be a file of at most 8 MiB.");
+    return readFileSync(path, "utf8");
+}

package/dist/resources/resourceDiscovery.js

@@ -179,8 +179,8 @@ function discoverRuntimeArtifacts(home, input) {
                 for (const launchEntry of safeReaddir(join(taskRoot, ownerEntry.name))) {
                     if (!launchEntry.isDirectory())
                         continue;
-                    const generationRoot = join(taskRoot, ownerEntry.name, launchEntry.name);
-                    const marker = readTaskRuntimeMarker(generationRoot);
+                    const runtimeRoot = join(taskRoot, ownerEntry.name, launchEntry.name);
+                    const marker = readTaskRuntimeMarker(runtimeRoot);
                     const owner = marker === undefined
                         ? { home, taskId, basis: "naming-convention" }
                         : {
@@ -193,9 +193,9 @@ function discoverRuntimeArtifacts(home, input) {
                     discovered.push({
                         record: createResourceRecord({
                             kind: "runtime-artifact",
-                            path: resolve(generationRoot),
+                            path: resolve(runtimeRoot),
                             owner,
-                            ...(sizeOf(generationRoot) === undefined ? {} : { sizeBytes: sizeOf(generationRoot) }),
+                            ...(sizeOf(runtimeRoot) === undefined ? {} : { sizeBytes: sizeOf(runtimeRoot) }),
                             cleanliness: "n/a",
                             activeRefs: [],
                             disposition: "active"
@@ -352,9 +352,9 @@ function readDeploymentGitMetadata(path) {
         return { repositoryPath: path };
     }
 }
-function readTaskRuntimeMarker(generationRoot) {
+function readTaskRuntimeMarker(runtimeRoot) {
     try {
-        const marker = JSON.parse(readFileSync(join(generationRoot, ".yui-task-runtime-owner.json"), "utf8"));
+        const marker = JSON.parse(readFileSync(join(runtimeRoot, ".yui-task-runtime-owner.json"), "utf8"));
         const owner = marker.descriptor?.workspace?.owner;
         if (owner === undefined || owner === null)
             return {};

package/dist/resources/resourceGc.js

@@ -125,7 +125,7 @@ function classifyDiscoveredResources(discovered, registry, scan, input, home) {
 }
 /**
  * Collect active workspace owner path fragments from durable state.
- * These protect resources that an active Session, Job, or Turn still
+ * These protect resources that an active Session, Job, or AgentRun still
  * references even when the Task itself is terminal.
  */
 function collectActiveWorkspaceOwners(input) {

package/dist/resources/resourceRegistrar.js

@@ -68,7 +68,7 @@ export class ResourceRegistrar {
     #registerTaskRuntimeIsolation(descriptor) {
         const owner = ownerFromManagedWorkspace(this.#home, descriptor.workspace.owner);
         this.#save([
-            descriptor.roots.generation,
+            descriptor.roots.runtime,
             descriptor.roots.data,
             descriptor.roots.cache,
             descriptor.roots.temporary

package/dist/resources/resourceTypes.js

@@ -30,7 +30,7 @@ export function isReleasable(record) {
 }
 /** Terminal Task statuses: a terminal owner keeps no active runtime claim. */
 export function isTerminalTaskStatus(status) {
-    return status === "completed" || status === "retired" || status === "archived";
+    return status === "completed" || status === "cancelled" || status === "archived";
 }
 /**
  * The immutable release namespace owned by the package installer (Issue 02).