@empire-builder-kit/nx 1.0.0-rc.4 → 1.0.0-rc.41

package/src/local-dev/task-identity.js

@@ -0,0 +1,418 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WORKTREE_GIT_QUERY_TIMEOUT_MS = exports.TASK_IDENTITY_SCHEMA_VERSION = exports.TASK_ID_PATTERN = void 0;
+exports.resolveTaskIdentityForAttachment = resolveTaskIdentityForAttachment;
+exports.assertCurrentTaskEnvironment = assertCurrentTaskEnvironment;
+exports.bindTaskEnvironment = bindTaskEnvironment;
+exports.attachTaskIdentity = attachTaskIdentity;
+exports.requireTaskId = requireTaskId;
+exports.taskStage = taskStage;
+exports.resolveWorktreeGitDirectory = resolveWorktreeGitDirectory;
+exports.taskIdentityPath = taskIdentityPath;
+exports.validateTaskIdentity = validateTaskIdentity;
+exports.resolveTaskIdentity = resolveTaskIdentity;
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const identity_js_1 = require("../workspace-deployment/identity.js");
+const contract_validation_js_1 = require("./contract-validation.js");
+const fleet_lock_js_1 = require("./fleet-lock.js");
+const process_identity_js_1 = require("./process-identity.js");
+const errors_js_1 = require("./errors.js");
+const private_state_js_1 = require("./private-state.js");
+exports.TASK_ID_PATTERN = /^[a-f0-9]{24}$/;
+exports.TASK_IDENTITY_SCHEMA_VERSION = 1;
+/** Git may reuse an admin pathname after remove/add. Birth identity survives
+ * worktree moves and pointer loss, but not destruction/recreation of the dir. */
+function worktreeAdministrationIdentity(workspaceRoot, priorReviewEncoding = false) {
+    const path = resolveWorktreeGitDirectory(workspaceRoot);
+    const stat = (0, node_fs_1.lstatSync)(path, { bigint: true });
+    if (!stat.isDirectory() || stat.isSymbolicLink() || stat.birthtimeNs <= 0n) {
+        throw new errors_js_1.LocalDevContractError('fleet-ownership-ambiguous', 'The Git administration filesystem must provide a positive directory birth time. Use a local filesystem that provides it; preserve existing task records and clean up or attach tasks on the original filesystem before moving. No task ownership was inferred.');
+    }
+    return (0, contract_validation_js_1.sha256Digest)({
+        path,
+        // Old, unshipped review records can still prove their exact original tuple.
+        // Never rewrite them or infer ownership from a mutable reflog. New records
+        // omit the mount-assigned device number; it is not directory identity.
+        ...(priorReviewEncoding ? { device: String(stat.dev) } : {}),
+        inode: String(stat.ino),
+        birthtimeNs: String(stat.birthtimeNs),
+    });
+}
+function publishTaskRecord(path, record, security) {
+    if ((0, node_fs_1.existsSync)(path))
+        return;
+    (0, private_state_js_1.publishPrivateFileExclusive)(path, `${JSON.stringify(record)}\n`, security);
+}
+function commonGitDirectory(workspaceRoot) {
+    const gitDirectory = resolveWorktreeGitDirectory(workspaceRoot);
+    const commonFile = (0, node_path_1.join)(gitDirectory, 'commondir');
+    // Resolve through Git rather than trusting a caller-supplied common directory.
+    if (!(0, node_fs_1.existsSync)(commonFile))
+        return gitDirectory;
+    const environment = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_')));
+    return (0, node_fs_1.realpathSync)((0, node_child_process_1.execFileSync)('git', [
+        '--no-optional-locks',
+        '-c',
+        'core.fsmonitor=false',
+        'rev-parse',
+        '--path-format=absolute',
+        '--git-common-dir',
+    ], {
+        cwd: workspaceRoot,
+        env: environment,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: gitQueryTimeout(),
+        windowsHide: true,
+    }).trim());
+}
+function registeredTaskPath(workspaceRoot, taskId) {
+    return (0, node_path_1.join)(commonGitDirectory(workspaceRoot), 'ebk', 'tasks', `${requireTaskId(taskId)}.json`);
+}
+/** Git keeps a linked worktree's administration directory stable across move. */
+function registeredTaskAdministrationDirectory(workspaceRoot, registered, security) {
+    const common = commonGitDirectory(workspaceRoot);
+    const worktrees = (0, node_path_1.join)(common, 'worktrees');
+    const candidates = [common];
+    if ((0, node_fs_1.existsSync)(worktrees)) {
+        if ((0, node_fs_1.lstatSync)(worktrees).isSymbolicLink()) {
+            throw new errors_js_1.LocalDevContractError('fleet-ownership-ambiguous', 'Git worktree administration must not be a symbolic link.');
+        }
+        const entries = (0, node_fs_1.readdirSync)(worktrees, { withFileTypes: true });
+        if (entries.length > 1024 ||
+            entries.some((entry) => !entry.isDirectory())) {
+            throw new errors_js_1.LocalDevContractError('fleet-ownership-ambiguous', 'Git worktree administration inventory is ambiguous; task attachment is refused.');
+        }
+        candidates.push(...entries.map((entry) => (0, node_path_1.join)(worktrees, entry.name)));
+    }
+    const matches = candidates.filter((directory) => {
+        const pointer = (0, node_path_1.join)(directory, 'ebk', 'task-v1.json');
+        if (!(0, node_fs_1.existsSync)(pointer))
+            return false;
+        (0, private_state_js_1.assertPrivatePath)((0, node_path_1.dirname)(pointer), 'directory', security);
+        const identity = validateTaskIdentity(JSON.parse((0, private_state_js_1.readPrivateFile)(pointer, security).toString('utf8')));
+        return (identity.taskId === registered.taskId &&
+            identity.workspaceRealpath === registered.workspaceRealpath);
+    });
+    if (matches.length !== 1) {
+        throw new errors_js_1.LocalDevContractError('fleet-ownership-ambiguous', 'Task attachment requires one exact retained Git administration pointer; restore its ownership evidence before retrying.');
+    }
+    return matches[0];
+}
+/** Only explicit attachment may inspect a moved pointer without changing it. */
+function resolveTaskIdentityForAttachment(workspaceRoot, requestedTaskId, security = {}) {
+    const pointer = taskIdentityPath(workspaceRoot);
+    if (!(0, node_fs_1.existsSync)(pointer))
+        return resolveTaskIdentity(workspaceRoot, security);
+    (0, private_state_js_1.assertPrivatePath)((0, node_path_1.dirname)(pointer), 'directory', security);
+    const identity = validateTaskIdentity(JSON.parse((0, private_state_js_1.readPrivateFile)(pointer, security).toString('utf8')));
+    if (identity.workspaceRealpath === (0, node_fs_1.realpathSync)(workspaceRoot)) {
+        return resolveTaskIdentity(workspaceRoot, security);
+    }
+    const registered = readRegisteredTask(workspaceRoot, requestedTaskId, security);
+    if (identity.taskId !== requestedTaskId ||
+        identity.workspaceRealpath !== registered.workspaceRealpath ||
+        registeredTaskAdministrationDirectory(workspaceRoot, registered, security) !== resolveWorktreeGitDirectory(workspaceRoot)) {
+        throw new errors_js_1.LocalDevContractError('fleet-ownership-ambiguous', 'Moved task attachment requires its exact retained Git administration identity.');
+    }
+    return identity;
+}
+function assertNoLostTaskPointer(workspaceRoot, security) {
+    const directory = (0, node_path_1.dirname)(registeredTaskPath(workspaceRoot, '0'.repeat(24)));
+    if (!(0, node_fs_1.existsSync)(directory))
+        return;
+    (0, private_state_js_1.assertPrivatePath)(directory, 'directory', security);
+    const names = (0, node_fs_1.readdirSync)(directory);
+    const administrationIdentity = worktreeAdministrationIdentity(workspaceRoot);
+    const priorReviewIdentity = worktreeAdministrationIdentity(workspaceRoot, true);
+    const retainedBindings = [];
+    if (names.length > 4096) {
+        throw new errors_js_1.LocalDevContractError('fleet-ownership-ambiguous', 'Task registry exceeds its bounded inventory.');
+    }
+    for (const name of names) {
+        if (!/^[a-f0-9]{24}\.json$/.test(name))
+            continue;
+        const registered = readRegisteredTask(workspaceRoot, name.slice(0, 24), security);
+        if (registered.administrationIdentity === administrationIdentity ||
+            registered.administrationIdentity === priorReviewIdentity ||
+            (!registered.administrationIdentityVersion &&
+                registered.workspaceRealpath === workspaceRoot)) {
+            // Another first resolver may have finished publishing while we inspected.
+            if ((0, node_fs_1.existsSync)(taskIdentityPath(workspaceRoot)))
+                return;
+            throw new errors_js_1.LocalDevContractError('fleet-ownership-ambiguous', 'This checkout has retained task ownership but its pointer is missing. Restore the exact private task pointer before startup; a new task will not be minted.');
+        }
+        if (registered.workspaceRealpath === workspaceRoot &&
+            registered.environment) {
+            retainedBindings.push(registered.taskId);
+        }
+    }
+    if (retainedBindings.length > 0) {
+        console.warn(`Retained task binding(s) for this recreated checkout: ${retainedBindings.slice(0, 16).join(', ')}${retainedBindings.length > 16 ? ` (${retainedBindings.length} total)` : ''}. These are not proof of live resources. Preserve their records and verify prior cleanup; attach before removing a source worktree. See docs/local-development.md and docs/upgrades.md#worktree-task-identity-migration.`);
+    }
+}
+function validateEnvironment(value) {
+    (0, contract_validation_js_1.assertRecord)(value, 'Task environment');
+    (0, contract_validation_js_1.assertExactProperties)(value, ['accountId', 'region', 'workspaceDeploymentId'], [], 'Task environment');
+    if (typeof value.accountId !== 'string' ||
+        !/^\d{12}$/.test(value.accountId) ||
+        typeof value.region !== 'string' ||
+        !/^[a-z]{2}(?:-gov)?-[a-z]+(?:-[a-z]+)*-\d$/.test(value.region) ||
+        typeof value.workspaceDeploymentId !== 'string' ||
+        !identity_js_1.WORKSPACE_DEPLOYMENT_ID_PATTERN.test(value.workspaceDeploymentId)) {
+        throw new errors_js_1.LocalDevContractError('invalid-state', 'Task environment requires a verified workspace, account, and Region.');
+    }
+    return {
+        accountId: value.accountId,
+        region: value.region,
+        workspaceDeploymentId: value.workspaceDeploymentId,
+    };
+}
+function readRegisteredTask(workspaceRoot, taskId, security) {
+    const path = registeredTaskPath(workspaceRoot, taskId);
+    (0, private_state_js_1.assertPrivatePath)((0, node_path_1.dirname)(path), 'directory', security);
+    (0, private_state_js_1.assertPrivatePath)((0, node_path_1.dirname)((0, node_path_1.dirname)(path)), 'directory', security);
+    const value = JSON.parse((0, private_state_js_1.readPrivateFile)(path, security).toString('utf8'));
+    (0, contract_validation_js_1.assertRecord)(value, 'Registered task');
+    (0, contract_validation_js_1.assertExactProperties)(value, ['schemaVersion', 'taskId', 'workspaceRealpath'], ['administrationIdentity', 'administrationIdentityVersion'], 'Registered task');
+    if (value.administrationIdentityVersion !== undefined &&
+        (value.administrationIdentityVersion !== 2 ||
+            typeof value.administrationIdentity !== 'string')) {
+        throw new errors_js_1.LocalDevContractError('invalid-state', 'Registered task administration version is malformed.');
+    }
+    if (value.administrationIdentity !== undefined &&
+        (typeof value.administrationIdentity !== 'string' ||
+            !/^[a-f0-9]{64}$/.test(value.administrationIdentity))) {
+        throw new errors_js_1.LocalDevContractError('invalid-state', 'Registered task administration identity is malformed.');
+    }
+    const identity = validateTaskIdentity({
+        schemaVersion: value.schemaVersion,
+        taskId: value.taskId,
+        workspaceRealpath: value.workspaceRealpath,
+    });
+    if (identity.taskId !== taskId)
+        throw new errors_js_1.LocalDevContractError('invalid-state', 'Registered task ID differs from its exact record.');
+    const environment = (0, node_fs_1.existsSync)(`${path}.environment`)
+        ? validateEnvironment(JSON.parse((0, private_state_js_1.readPrivateFile)(`${path}.environment`, security).toString('utf8')))
+        : undefined;
+    // Enrollment of an intact older pointer uses an exclusive sidecar, never a
+    // read/modify/write of authority that could race an explicit attachment.
+    const administrationIdentity = value.administrationIdentity ??
+        ((0, node_fs_1.existsSync)(`${path}.administration`)
+            ? (0, private_state_js_1.readPrivateFile)(`${path}.administration`, security)
+                .toString('utf8')
+                .trim()
+            : undefined);
+    if (administrationIdentity !== undefined &&
+        (typeof administrationIdentity !== 'string' ||
+            !/^[a-f0-9]{64}$/.test(administrationIdentity))) {
+        throw new errors_js_1.LocalDevContractError('invalid-state', 'Registered task administration identity is malformed.');
+    }
+    return {
+        ...identity,
+        ...(value.administrationIdentityVersion === 2
+            ? { administrationIdentityVersion: 2 }
+            : {}),
+        ...(typeof administrationIdentity === 'string'
+            ? { administrationIdentity }
+            : {}),
+        ...(environment ? { environment } : {}),
+    };
+}
+function sameEnvironment(left, right) {
+    return (left.accountId === right.accountId &&
+        left.region === right.region &&
+        left.workspaceDeploymentId === right.workspaceDeploymentId);
+}
+/** Cleanup requires an already-bound task; it may not establish new authority. */
+function assertCurrentTaskEnvironment(workspaceRoot, environment, security = {}) {
+    const identity = resolveTaskIdentity(workspaceRoot, security);
+    const registered = readRegisteredTask(workspaceRoot, identity.taskId, security);
+    if (!registered.environment ||
+        !sameEnvironment(registered.environment, validateEnvironment(environment))) {
+        throw new errors_js_1.LocalDevContractError('configuration-mismatch', 'Task cleanup requires its previously bound workspace, AWS account, and Region.');
+    }
+    return identity;
+}
+/** The caller must establish this tuple through current STS and workspace ownership checks. */
+function bindTaskEnvironment(workspaceRoot, environment, security = {}) {
+    const identity = resolveTaskIdentity(workspaceRoot, security);
+    const verified = validateEnvironment(environment);
+    const environmentPath = `${registeredTaskPath(workspaceRoot, identity.taskId)}.environment`;
+    if (!(0, node_fs_1.existsSync)(environmentPath)) {
+        (0, private_state_js_1.publishPrivateFileExclusive)(environmentPath, `${JSON.stringify(verified)}\n`, security);
+    }
+    const registered = readRegisteredTask(workspaceRoot, identity.taskId, security);
+    if (registered.environment &&
+        !sameEnvironment(registered.environment, verified)) {
+        throw new errors_js_1.LocalDevContractError('configuration-mismatch', 'Task is bound to a different workspace, AWS account, or Region. Restore its configured context.');
+    }
+}
+/** Called while holding the existing task fleet lock, after proving no runner or cleanup remains. */
+function attachTaskIdentity(workspaceRoot, taskId, environment, security = {}) {
+    const verified = validateEnvironment(environment);
+    const registered = readRegisteredTask(workspaceRoot, requireTaskId(taskId), security);
+    if (!registered.environment ||
+        !sameEnvironment(registered.environment, verified)) {
+        throw new errors_js_1.LocalDevContractError('configuration-mismatch', 'Task reattachment requires its verified workspace, AWS account, and Region; unbound tasks cannot be transferred.');
+    }
+    const administrationDirectory = registeredTaskAdministrationDirectory(workspaceRoot, registered, security);
+    const nativeDirectory = (0, node_path_1.join)(administrationDirectory, 'ebk', 'native-writers');
+    const gatePath = (0, node_path_1.join)(nativeDirectory, `${taskId}.gate.json`);
+    const gate = (0, fleet_lock_js_1.acquireFleetLock)(gatePath, {
+        fleetId: `task-${taskId}`,
+        owner: (0, process_identity_js_1.captureProcessIdentity)(),
+        sessionGeneration: (0, contract_validation_js_1.sha256Digest)({
+            root: registered.workspaceRealpath,
+            taskId,
+        }),
+    }, security);
+    if (gate.kind !== 'acquired')
+        throw new errors_js_1.LocalDevContractError('fleet-ownership-ambiguous', 'Task reattachment requires exclusive native writer registration.');
+    try {
+        if (JSON.stringify(readRegisteredTask(workspaceRoot, taskId, security)) !==
+            JSON.stringify(registered) ||
+            registeredTaskAdministrationDirectory(workspaceRoot, registered, security) !== administrationDirectory) {
+            throw new errors_js_1.LocalDevContractError('fleet-ownership-ambiguous', 'Task ownership changed during native writer registration.');
+        }
+        if ((0, node_fs_1.existsSync)((0, node_path_1.join)(nativeDirectory, taskId)) &&
+            (0, node_fs_1.readdirSync)((0, node_path_1.join)(nativeDirectory, taskId)).length > 0) {
+            throw new errors_js_1.LocalDevContractError('fleet-ownership-ambiguous', 'Task reattachment cannot move retained native writer ownership; finish exact-task recovery first.');
+        }
+        const identity = {
+            schemaVersion: exports.TASK_IDENTITY_SCHEMA_VERSION,
+            taskId,
+            workspaceRealpath: (0, node_fs_1.realpathSync)(workspaceRoot),
+        };
+        // Persist the authoritative owner first. An interrupted pointer write leaves
+        // both old startup and attachment closed, rather than two accepted owners.
+        (0, private_state_js_1.atomicWritePrivateFile)(registeredTaskPath(workspaceRoot, taskId), `${JSON.stringify({ ...identity, administrationIdentity: worktreeAdministrationIdentity(workspaceRoot), administrationIdentityVersion: 2 })}\n`, security);
+        (0, private_state_js_1.atomicWritePrivateFile)(taskIdentityPath(workspaceRoot), `${JSON.stringify(identity)}\n`, security);
+        return identity;
+    }
+    finally {
+        (0, fleet_lock_js_1.releaseFleetLock)(gatePath, gate.record, security);
+    }
+}
+function requireTaskId(value) {
+    if (typeof value !== 'string' || !exports.TASK_ID_PATTERN.test(value)) {
+        throw new errors_js_1.LocalDevContractError('personal-identity-unavailable', 'Task identity must be an opaque 24-character lowercase hexadecimal ID.');
+    }
+    return value;
+}
+function taskStage(taskId) {
+    return `personal-${requireTaskId(taskId)}`;
+}
+/** Git query budget: hosted Windows runners answer slowly under child contention
+ * (eight simultaneous resolvers exceeded 5 s in PR #113 diagnostic 34737069666). */
+exports.WORKTREE_GIT_QUERY_TIMEOUT_MS = Object.freeze({
+    default: 5_000,
+    win32: 30_000,
+});
+function gitQueryTimeout() {
+    return process.platform === 'win32'
+        ? exports.WORKTREE_GIT_QUERY_TIMEOUT_MS.win32
+        : exports.WORKTREE_GIT_QUERY_TIMEOUT_MS.default;
+}
+function resolveWorktreeGitDirectory(workspaceRoot) {
+    // Ignore caller Git overrides: the selected checkout, not ambient Git state,
+    // owns its task pointer. --absolute-git-dir works before the first commit.
+    const environment = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_')));
+    try {
+        return (0, node_fs_1.realpathSync)((0, node_child_process_1.execFileSync)('git', [
+            '--no-optional-locks',
+            '-c',
+            'core.fsmonitor=false',
+            'rev-parse',
+            '--absolute-git-dir',
+        ], {
+            cwd: workspaceRoot,
+            encoding: 'utf8',
+            env: environment,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            timeout: gitQueryTimeout(),
+            windowsHide: true,
+        }).trim());
+    }
+    catch {
+        throw new errors_js_1.LocalDevContractError('personal-identity-unavailable', 'Task development requires a Git worktree. Initialize the generated repository before running ebk dev.');
+    }
+}
+function taskIdentityPath(workspaceRoot) {
+    return (0, node_path_1.join)(resolveWorktreeGitDirectory(workspaceRoot), 'ebk', 'task-v1.json');
+}
+function validateTaskIdentity(value) {
+    (0, contract_validation_js_1.assertRecord)(value, 'Task identity');
+    (0, contract_validation_js_1.assertExactProperties)(value, ['schemaVersion', 'taskId', 'workspaceRealpath'], [], 'Task identity');
+    if (value.schemaVersion !== exports.TASK_IDENTITY_SCHEMA_VERSION ||
+        typeof value.workspaceRealpath !== 'string' ||
+        value.workspaceRealpath.length === 0) {
+        throw new errors_js_1.LocalDevContractError('invalid-state', 'Task identity is malformed.');
+    }
+    return {
+        schemaVersion: exports.TASK_IDENTITY_SCHEMA_VERSION,
+        taskId: requireTaskId(value.taskId),
+        workspaceRealpath: value.workspaceRealpath,
+    };
+}
+function resolveTaskIdentity(workspaceRoot, security = {}) {
+    const workspaceRealpath = (0, node_fs_1.realpathSync)(workspaceRoot);
+    const path = taskIdentityPath(workspaceRealpath);
+    // Refuse unsupported filesystems before publishing even the first pointer.
+    const administrationIdentity = worktreeAdministrationIdentity(workspaceRealpath);
+    // A dangling symlink is evidence, not an absent pointer to replace.
+    let pointerExists = false;
+    try {
+        (0, node_fs_1.lstatSync)(path);
+        pointerExists = true;
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    if (!pointerExists)
+        assertNoLostTaskPointer(workspaceRealpath, security);
+    publishTaskRecord(path, {
+        schemaVersion: exports.TASK_IDENTITY_SCHEMA_VERSION,
+        taskId: (0, node_crypto_1.randomBytes)(12).toString('hex'),
+        workspaceRealpath,
+    }, security);
+    (0, private_state_js_1.assertPrivatePath)((0, node_path_1.join)(resolveWorktreeGitDirectory(workspaceRealpath), 'ebk'), 'directory', security);
+    const record = validateTaskIdentity(JSON.parse((0, private_state_js_1.readPrivateFile)(path, security).toString('utf8')));
+    if (record.workspaceRealpath !== workspaceRealpath) {
+        throw new errors_js_1.LocalDevContractError('fleet-ownership-ambiguous', 'Task belongs to a different checkout. Use explicit ebk dev attach after verifying its ownership; startup will not reassign it.');
+    }
+    publishTaskRecord(registeredTaskPath(workspaceRealpath, record.taskId), {
+        ...record,
+        administrationIdentity,
+        administrationIdentityVersion: 2,
+    }, security);
+    const registered = readRegisteredTask(workspaceRealpath, record.taskId, security);
+    if (worktreeAdministrationIdentity(workspaceRealpath) !== administrationIdentity) {
+        throw new errors_js_1.LocalDevContractError('fleet-ownership-ambiguous', 'Git administration identity changed while resolving task ownership; no ownership was inferred.');
+    }
+    if (registered.workspaceRealpath !== workspaceRealpath) {
+        throw new errors_js_1.LocalDevContractError('fleet-ownership-ambiguous', 'Task was explicitly attached to another worktree. This checkout no longer owns its task environment.');
+    }
+    if (!registered.administrationIdentity) {
+        // Enroll only an intact pointer already reconciled with its registry above.
+        // Missing-pointer recovery cannot use this path or invent old ownership.
+        (0, private_state_js_1.publishPrivateFileExclusive)(`${registeredTaskPath(workspaceRealpath, record.taskId)}.administration`, `${administrationIdentity}\n`, security);
+        const enrolled = readRegisteredTask(workspaceRealpath, record.taskId, security);
+        if (enrolled.workspaceRealpath !== workspaceRealpath ||
+            enrolled.administrationIdentity !== administrationIdentity) {
+            throw new errors_js_1.LocalDevContractError('fleet-ownership-ambiguous', 'Task ownership changed during administration enrollment; no pointer was reassigned.');
+        }
+    }
+    else if (registered.administrationIdentity !== administrationIdentity &&
+        (registered.administrationIdentityVersion !== undefined ||
+            registered.administrationIdentity !==
+                worktreeAdministrationIdentity(workspaceRealpath, true))) {
+        throw new errors_js_1.LocalDevContractError('fleet-ownership-ambiguous', 'Task belongs to a different Git administration generation; its pointer cannot be adopted by a recreated worktree.');
+    }
+    return record;
+}
+//# sourceMappingURL=task-identity.js.map

package/src/local-dev/task-native-writer.d.ts

@@ -0,0 +1,18 @@
+import type { ExecutorContext } from '@nx/devkit';
+import { type FleetProcessIdentity, type ProcessIdentityProbe } from './fleet-lock.js';
+import { type PrivateStateSecurity } from './private-state.js';
+export interface TaskNativeWriterEffects {
+    appData?: string;
+    processProbe?: (identity: FleetProcessIdentity) => ProcessIdentityProbe;
+    security?: PrivateStateSecurity;
+    groupExists?: (pid: number) => boolean;
+}
+/** Read-only legacy/current runner proof; cleanup need not have succeeded to unlock. */
+export declare function assertTaskNativeWritersAbsent(context: ExecutorContext, effects?: TaskNativeWriterEffects): void;
+export interface TaskNativeWriterLease {
+    assertCurrent(): void;
+    recordChild(pid: number, ownsProcessGroup?: boolean): void;
+    release(): void;
+}
+/** One native invocation per exact worktree/task/Slice, never a global task lock. */
+export declare function acquireTaskNativeWriterLease(context: ExecutorContext, taskId: string, unlock: boolean, effects?: TaskNativeWriterEffects): TaskNativeWriterLease;