@playcraft/cli 0.1.29 → 0.1.31

package/dist/utils/agent-api-client.js

@@ -1,8 +1,12 @@
 import { readFileSync, existsSync } from 'fs';
-import { join } from 'path';
+import { dirname, join } from 'path';
 import { homedir } from 'os';
 import { loadGlobalConfig } from '../config.js';
 import { DEFAULT_PLAYCRAFT_CLOUD_BASE } from '../commands/login.js';
+import { AGENT_TOOL_OPERATION_PROTOCOL, AGENT_TOOL_OPERATION_HEADERS, AGENT_TOOL_OPERATION_CAPABILITIES_PATH, } from '@playcraft/common/agent-tools';
+import { beginToolOperation } from './tool-operation-journal.js';
+import { businessEndpoint } from './environment-endpoints.js';
+import { AccountActivationError, parseErrorPayload, pendingAccountActivationError, } from '../auth/account-activation.js';
 /**
  * 判断 token 是否为用户 PAT（Personal Access Token）。
  * PAT 以 "playcraft_pat_" 开头；沙箱 JWT 为三段式 base64。
@@ -15,8 +19,8 @@ function isPatToken(token) {
  * or from the CLI after `playcraft login`.
  *
  * 凭证解析优先级：
- *   API URL : PLAYCRAFT_API_URL → .playcraft.json → ~/.playcraft/config.json → DEFAULT_PLAYCRAFT_CLOUD_BASE
- *   Token   : PLAYCRAFT_SANDBOX_TOKEN → .playcraft.json token → ~/.playcraft/config.json token (PAT)
+ *   API URL : PLAYCRAFT_API_URL → sandbox global .playcraft.json → project .playcraft.json → ~/.playcraft/config.json → DEFAULT_PLAYCRAFT_CLOUD_BASE
+ *   Token   : PLAYCRAFT_SANDBOX_TOKEN → sandbox global .playcraft.json → project .playcraft.json → ~/.playcraft/config.json token (PAT)
  *
  * 鉴权 header 自动选择：
  *   - 沙箱 JWT (非 PAT) → X-Sandbox-Token: <token>（后端 @SandboxToken 路由的沙箱分支）
@@ -25,7 +29,7 @@ function isPatToken(token) {
 export class AgentApiClient {
     apiUrl;
     token;
-    isPat;
+    credentialFile;
     playcraftEnv;
     constructor() {
         const localConfig = AgentApiClient.loadLocalConfig();
@@ -36,7 +40,7 @@ export class AgentApiClient {
             globalConfig.backendUrl ||
             globalConfig.url ||
             DEFAULT_PLAYCRAFT_CLOUD_BASE).replace(/\/+$/, '');
-        // Token: 沙箱 token 环境变量 → 本地 .playcraft.json → 全局 login 配置（PAT）
+        // Token: 环境变量 → 沙箱全局配置 → 项目配置 → 用户登录配置
         const token = process.env.PLAYCRAFT_SANDBOX_TOKEN ||
             localConfig.token ||
             globalConfig.token ||
@@ -47,43 +51,147 @@ export class AgentApiClient {
         }
         this.apiUrl = apiUrl;
         this.token = token;
-        this.isPat = isPatToken(token);
-        this.playcraftEnv = (process.env.PLAYCRAFT_ENV ||
-            localConfig.env ||
-            '').trim();
+        this.credentialFile = localConfig.credentialFile;
+        this.playcraftEnv = (process.env.PLAYCRAFT_ENV || localConfig.env || '').trim();
     }
     /** 根据 token 类型构造鉴权 headers */
     authHeaders() {
-        const headers = this.isPat
-            ? { Authorization: `Bearer ${this.token}` }
-            : { 'X-Sandbox-Token': this.token };
+        let token = this.token;
+        // Polling commands can outlive a credential: read the atomically refreshed file per request.
+        if (this.credentialFile && !process.env.PLAYCRAFT_SANDBOX_TOKEN) {
+            try {
+                token = JSON.parse(readFileSync(this.credentialFile, 'utf8')).token || token;
+            }
+            catch { /* Keep the last credential if a local file is temporarily unavailable. */ }
+        }
+        const headers = isPatToken(token)
+            ? { Authorization: `Bearer ${token}` }
+            : { 'X-Sandbox-Token': token };
         if (this.playcraftEnv) {
             headers['playcraft-env'] = this.playcraftEnv;
         }
         return headers;
     }
-    /** Absolute pathname under /api/agent/tools (path may omit leading slash). */
+    /** Deployment-relative pathname under /api/agent/tools (path may omit leading slash). */
     toolsRequestUrl(path) {
         const p = path.startsWith('/') ? path : `/${path}`;
-        return new URL(`/api/agent/tools${p}`, this.apiUrl);
+        return businessEndpoint(this.apiUrl, `/api/agent/tools${p}`);
     }
-    async post(path, body) {
-        const url = this.toolsRequestUrl(path).href;
-        const res = await fetch(url, {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                ...this.authHeaders(),
-            },
-            body: JSON.stringify(body),
+    async post(path, body, options) {
+        const url = this.toolsRequestUrl(path);
+        const serializedBody = JSON.stringify(body);
+        if (serializedBody === undefined)
+            throw new Error('Tool request body is required');
+        const recoverId = options?.requestId ?? process.env.PLAYCRAFT_TOOL_REQUEST_ID;
+        const operation = beginToolOperation(url.pathname, serializedBody, recoverId, {
+            newRequest: options?.newRequest ?? process.env.PLAYCRAFT_TOOL_NEW_REQUEST === '1',
         });
-        if (!res.ok) {
-            const text = await res.text().catch(() => res.statusText);
-            throw new Error(`API ${res.status}: ${text}`);
+        const unknownOutcome = `Tool request ${operation.requestId}: the outcome is unknown. Rerun the same command to ` +
+            `continue this request: it returns the result if the request finished, or finishes it if ` +
+            `the tool can be safely redone; it never starts a second operation. Record: ${operation.file}.`;
+        try {
+            try {
+                await options?.onPrepared?.({ requestId: operation.requestId, file: operation.file });
+            }
+            catch {
+                operation.reject();
+                throw new ToolRequestError('Tool request preparation failed; no operation was sent');
+            }
+            const capabilityResponse = await fetch(this.toolsRequestUrl(AGENT_TOOL_OPERATION_CAPABILITIES_PATH), {
+                headers: this.authHeaders(),
+                redirect: 'error',
+                signal: options?.signal
+                    ? AbortSignal.any([options.signal, AbortSignal.timeout(30_000)])
+                    : AbortSignal.timeout(30_000),
+            });
+            if (!capabilityResponse.ok) {
+                if (capabilityResponse.status === 403) {
+                    const pending = pendingAccountActivationError(403, parseErrorPayload(await capabilityResponse.clone().text().catch(() => '')));
+                    if (pending) {
+                        if (operation.createdNew && !operation.settledOnly)
+                            operation.reject();
+                        throw pending;
+                    }
+                }
+                await capabilityResponse.body?.cancel();
+                throw new ToolRequestError(`Business tool protocol unavailable (${capabilityResponse.status}); no operation was sent`);
+            }
+            const capabilities = (await capabilityResponse.json());
+            if (capabilities.protocol !== AGENT_TOOL_OPERATION_PROTOCOL ||
+                capabilities.settledOnly !== true)
+                throw new ToolRequestError('Business tool protocol is incompatible; no operation was sent');
+            const res = await fetch(url, {
+                method: 'POST',
+                redirect: 'error',
+                signal: options?.signal
+                    ? AbortSignal.any([options.signal, AbortSignal.timeout(30 * 60_000)])
+                    : AbortSignal.timeout(30 * 60_000),
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...this.authHeaders(),
+                    [AGENT_TOOL_OPERATION_HEADERS.protocol]: AGENT_TOOL_OPERATION_PROTOCOL,
+                    [AGENT_TOOL_OPERATION_HEADERS.requestId]: operation.requestId,
+                    ...(operation.settledOnly ? { [AGENT_TOOL_OPERATION_HEADERS.settledOnly]: 'true' } : {}),
+                },
+                body: serializedBody,
+            });
+            if (res.headers.get(AGENT_TOOL_OPERATION_HEADERS.protocol) !== AGENT_TOOL_OPERATION_PROTOCOL ||
+                res.headers.get(AGENT_TOOL_OPERATION_HEADERS.requestId) !== operation.requestId) {
+                if (res.status === 403) {
+                    const pending = pendingAccountActivationError(403, parseErrorPayload(await res.clone().text().catch(() => '')));
+                    if (pending) {
+                        if (operation.createdNew && !operation.settledOnly)
+                            operation.reject();
+                        throw pending;
+                    }
+                }
+                await res.body?.cancel();
+                // Possibly an instance that ignores identities: a rerun may only read the receipt.
+                operation.requireReceipt();
+                throw new Error('Business did not acknowledge a durable receipt; outcome remains unconfirmed');
+            }
+            if (!res.ok) {
+                const text = await res.text().catch(() => res.statusText);
+                const pending = pendingAccountActivationError(res.status, parseErrorPayload(text));
+                if (pending)
+                    throw pending;
+                const code = errorCode(text);
+                if (res.status === 409 && code === 'business_operation_in_progress')
+                    throw new ToolRequestError(`API 409: ${text}\nTool request ${operation.requestId} is still running. Rerun the ` +
+                        'same command later to get its result.');
+                if (res.status === 409 && code === 'business_operation_requires_reconciliation')
+                    throw new ToolRequestError(recoverId !== undefined
+                        ? // A receipt query never runs the request, even for a tool that can be safely redone.
+                            `API 409: ${text}\nTool request ${operation.requestId} has no settled result yet. ` +
+                                'Rerun the same command without PLAYCRAFT_TOOL_REQUEST_ID: a tool that can be ' +
+                                'safely redone continues this request; any other tool then needs reconciliation.'
+                        : `API 409: ${text}\nTool request ${operation.requestId} needs reconciliation: its ` +
+                            'outcome is unknown, and rerunning the same command will not run it again. Only ' +
+                            'after confirming it had no effect, rerun with PLAYCRAFT_TOOL_NEW_REQUEST=1 to ' +
+                            'start a new operation.');
+                if (res.status >= 400 && res.status < 500) {
+                    // The request itself was refused and not carried out: a rerun is a new operation.
+                    operation.reject();
+                    throw new ToolRequestError(`API ${res.status}: ${text}`);
+                }
+                throw new Error(`API ${res.status}: ${text}`);
+            }
+            const result = (await res.json());
+            operation.complete();
+            return result;
+        }
+        catch (error) {
+            if (error instanceof ToolRequestError || error instanceof AccountActivationError)
+                throw error;
+            throw new Error(`${error instanceof Error ? error.message : String(error)}\n${operation.settledOnly
+                ? `Tool request ${operation.requestId}; record: ${operation.file}. Its settled result is not available yet.`
+                : unknownOutcome}`);
+        }
+        finally {
+            operation.release();
         }
-        return res.json();
     }
-    async get(path, params) {
+    async get(path, params, options) {
         const url = this.toolsRequestUrl(path);
         if (params) {
             for (const [k, v] of Object.entries(params)) {
@@ -93,27 +201,62 @@ export class AgentApiClient {
         }
         const res = await fetch(url, {
             headers: this.authHeaders(),
+            redirect: 'error',
+            signal: options?.signal ?? AbortSignal.timeout(30_000),
         });
         if (!res.ok) {
             const text = await res.text().catch(() => res.statusText);
+            const pending = pendingAccountActivationError(res.status, parseErrorPayload(text));
+            if (pending)
+                throw pending;
             throw new Error(`API ${res.status}: ${text}`);
         }
         return res.json();
     }
+    /** Stream only to the authenticated, same-service video upload endpoint. */
+    async putVideoMedia(path, body, headers, signal) {
+        if (!/^\/video-media\/[a-f0-9-]{36}\/content\?/.test(path))
+            throw new Error('invalid_video_upload_target');
+        const url = this.toolsRequestUrl(path);
+        const keys = [...url.searchParams.keys()].sort();
+        if (keys.join(',') !== 'expires,signature,workspaceId')
+            throw new Error('invalid_video_upload_target');
+        const allowed = new Set(['content-type', 'content-md5', 'content-length']);
+        if (Object.keys(headers).some(key => !allowed.has(key.toLowerCase())))
+            throw new Error('invalid_video_upload_headers');
+        const response = await fetch(url, {
+            method: 'PUT', redirect: 'error', signal,
+            headers: { ...headers, ...this.authHeaders() },
+            body: body,
+            duplex: 'half',
+        });
+        if (!response.ok) {
+            await response.body?.cancel();
+            throw new Error(`video_upload_failed:${response.status}`);
+        }
+        await response.body?.cancel();
+    }
     /**
      * 按顺序搜索本地 .playcraft.json 文件（沙箱内或项目目录）。
      * 与全局 login 配置（~/.playcraft/config.json）不同，前者专用于沙箱 token。
      */
     static loadLocalConfig() {
+        const ancestors = [];
+        for (let directory = process.cwd();; directory = dirname(directory)) {
+            ancestors.push(join(directory, '.playcraft.json'));
+            if (dirname(directory) === directory)
+                break;
+        }
         const searchPaths = [
-            join(process.cwd(), '.playcraft.json'),
+            process.env.PLAYCRAFT_SANDBOX_CONFIG_PATH || '/workspaces/.playcraft.json',
+            ...ancestors,
             '/project/.playcraft.json',
             join(homedir(), '.playcraft.json'),
         ];
         for (const p of searchPaths) {
             if (existsSync(p)) {
                 try {
-                    return JSON.parse(readFileSync(p, 'utf-8'));
+                    return { ...JSON.parse(readFileSync(p, 'utf-8')), credentialFile: p };
                 }
                 catch {
                     continue;
@@ -123,3 +266,15 @@ export class AgentApiClient {
         return { apiUrl: '', token: '' };
     }
 }
+/** A failure whose meaning is settled; no recovery hint applies. */
+class ToolRequestError extends Error {
+}
+function errorCode(text) {
+    try {
+        const message = JSON.parse(text).message;
+        return typeof message === 'string' ? message : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/utils/environment-endpoints.js

@@ -0,0 +1,17 @@
+function publicBase(value) {
+    const base = new URL(value);
+    if (!['http:', 'https:'].includes(base.protocol) || base.username || base.password || base.search || base.hash) {
+        throw new Error('invalid_environment_endpoint');
+    }
+    base.pathname = base.pathname.replace(/\/+$/, '');
+    return base;
+}
+function append(base, path) {
+    return new URL(`${base.toString().replace(/\/+$/, '')}/${path.replace(/^\/+/, '')}`);
+}
+/** Accept either a public deployment base or its /api endpoint, without duplicating /api. */
+export function businessEndpoint(apiUrl, path) {
+    const base = publicBase(apiUrl);
+    base.pathname = base.pathname.replace(/\/api$/, '');
+    return append(base, path);
+}

package/dist/utils/playcraft-http-client.js

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { loadGlobalConfig } from '../config.js';
 import { DEFAULT_PLAYCRAFT_CLOUD_BASE } from '../commands/login.js';
+import { pendingAccountActivationError } from '../auth/account-activation.js';
 export class PlayCraftApiError extends Error {
     code;
     status;
@@ -95,19 +96,20 @@ export class PlayCraftHttpClient {
                 }
                 if (!response.ok) {
                     const error = payload?.error;
-                    const code = typeof error?.code === 'string' ? error.code : statusCode(response.status);
-                    const message = typeof error?.message === 'string'
+                    const pending = pendingAccountActivationError(response.status, payload);
+                    const code = pending?.code ?? (typeof error?.code === 'string' ? error.code : statusCode(response.status));
+                    const message = pending?.message ?? (typeof error?.message === 'string'
                         ? error.message
                         : typeof payload?.message === 'string'
                             ? payload.message
                             : typeof payload === 'string'
                                 ? payload
-                                : response.statusText || 'PlayCraft request failed';
+                                : response.statusText || 'PlayCraft request failed');
                     throw new PlayCraftApiError({
                         code,
                         message,
                         status: response.status,
-                        details: error?.details ?? payload,
+                        details: pending ? { loginCommand: 'playcraft login --activate' } : error?.details ?? payload,
                         retryable: response.status >= 500,
                     });
                 }

package/dist/utils/tool-operation-journal.js

@@ -0,0 +1,124 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdirSync, readdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+import { isAgentToolRequestId } from '@playcraft/common/agent-tools';
+/** Operations this process is sending now; never continued by another call of this process. */
+const inFlight = new Set();
+/** Linux start time of a process, so a reused pid is not taken for the process that held it. */
+function startOf(pid) {
+    try {
+        const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+        return stat.slice(stat.lastIndexOf(')') + 2).split(' ')[19] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function holderAlive(holder) {
+    if (!holder || holder.pid === process.pid)
+        return false;
+    try {
+        process.kill(holder.pid, 0);
+    }
+    catch (error) {
+        if (error.code !== 'EPERM')
+            return false;
+    }
+    return holder.start === null || startOf(holder.pid) === holder.start;
+}
+/** Persist an identity before sending. Store neither credentials nor request/response bodies. */
+export function beginToolOperation(path, serializedBody, recoverId, options = {}) {
+    const directory = process.env.PLAYCRAFT_TOOL_REQUEST_DIR ?? join(homedir(), '.playcraft', 'tool-requests');
+    if (!isAbsolute(directory))
+        throw new Error('PLAYCRAFT_TOOL_REQUEST_DIR must be an absolute path');
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const inputHash = createHash('sha256').update(serializedBody).digest('hex');
+    // Rerunning the same command while its outcome is unknown continues that operation: the server
+    // answers the same identity with its receipt instead of running it again.
+    const unconfirmed = recoverId === undefined && !options.newRequest
+        ? findUnconfirmed(directory, path, inputHash)
+        : undefined;
+    const identifier = recoverId ?? unconfirmed?.requestId ?? randomUUID();
+    if (!isAgentToolRequestId(identifier))
+        throw new Error('Invalid PLAYCRAFT_TOOL_REQUEST_ID');
+    const requestId = identifier.toLowerCase();
+    const file = join(directory, `${requestId}.json`);
+    const now = new Date().toISOString();
+    const holder = { pid: process.pid, start: startOf(process.pid) };
+    const entry = {
+        version: 1,
+        requestId,
+        path,
+        inputHash,
+        state: 'unconfirmed',
+        holder,
+        createdAt: now,
+        updatedAt: now,
+    };
+    let createdNew = false;
+    try {
+        writeFileSync(file, JSON.stringify(entry), { flag: 'wx', mode: 0o600 });
+        createdNew = true;
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        const previous = JSON.parse(readFileSync(file, 'utf8'));
+        if (previous.version !== 1 ||
+            previous.requestId !== requestId ||
+            previous.path !== path ||
+            previous.inputHash !== inputHash)
+            throw new Error(`Tool request ${requestId} conflicts with its durable local record`);
+    }
+    const update = (change) => {
+        const current = JSON.parse(readFileSync(file, 'utf8'));
+        const temporary = `${file}.${randomUUID()}.tmp`;
+        writeFileSync(temporary, JSON.stringify({ ...current, ...change, updatedAt: new Date().toISOString() }), { flag: 'wx', mode: 0o600 });
+        renameSync(temporary, file);
+    };
+    // Only the sender holds an operation; a concurrent run of the same command gets its own.
+    inFlight.add(requestId);
+    if (unconfirmed || recoverId !== undefined)
+        update({ holder });
+    return {
+        requestId,
+        /** This call created the identity; a refusal cannot settle an older unknown operation. */
+        createdNew,
+        /** An explicit recovery, or a server that did not acknowledge the identity, reads only. */
+        settledOnly: recoverId !== undefined || unconfirmed?.receiptOnly === true,
+        file,
+        complete: () => update({ state: 'completed' }),
+        /** A definite refusal: the request was not carried out, so a rerun is a new operation. */
+        reject: () => update({ state: 'rejected' }),
+        /** The outcome stays unknown and a rerun may only read the receipt. */
+        requireReceipt: () => update({ receiptOnly: true }),
+        /** This call is done with the operation; a later run of the command may continue it. */
+        release: () => inFlight.delete(requestId),
+    };
+}
+function findUnconfirmed(directory, path, inputHash) {
+    let latest;
+    for (const name of readdirSync(directory)) {
+        if (!name.endsWith('.json'))
+            continue;
+        try {
+            const entry = JSON.parse(readFileSync(join(directory, name), 'utf8'));
+            if (entry.version === 1 &&
+                entry.state === 'unconfirmed' &&
+                entry.path === path &&
+                entry.inputHash === inputHash &&
+                isAgentToolRequestId(entry.requestId) &&
+                (!latest || entry.updatedAt > latest.updatedAt) &&
+                // Still being sent, here or by another live process: that run is not interrupted.
+                // Checked last, so only this command's candidates cost a process probe.
+                !inFlight.has(entry.requestId) &&
+                !holderAlive(entry.holder))
+                latest = entry;
+        }
+        catch {
+            // A torn or foreign file is not an operation of this command.
+        }
+    }
+    return latest;
+}

package/dist/utils/video-evidence-git.js

@@ -0,0 +1,81 @@
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, realpath } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+const ENTRY = '/.playcraft/video-replication/';
+/** Keep local analysis evidence out of a repository without changing its tracked ignore rules. */
+export async function ensureVideoEvidenceGitExcluded(directory) {
+    let root = await realpath(directory);
+    while (true) {
+        const marker = await lstat(join(root, '.git')).catch((error) => {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        });
+        if (marker) {
+            // Cloud workspaces own a real .git directory; never follow a redirected Git metadata tree.
+            if (!marker.isDirectory() || marker.isSymbolicLink())
+                return false;
+            try {
+                await appendExclude(root);
+                return true;
+            }
+            catch (error) {
+                if (['EACCES', 'EPERM', 'EROFS'].includes(error.code ?? ''))
+                    return false;
+                throw error;
+            }
+        }
+        const parent = dirname(root);
+        if (parent === root)
+            return true;
+        root = parent;
+    }
+}
+async function appendExclude(root) {
+    const flags = constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW;
+    const handles = [];
+    let file;
+    try {
+        const directory = await open(root, flags);
+        handles.push(directory);
+        const pinned = (handle, fallback) => process.platform === 'linux' ? `/proc/self/fd/${handle.fd}` : fallback;
+        const git = await open(join(pinned(directory, root), '.git'), flags);
+        handles.push(git);
+        const gitPath = pinned(git, join(root, '.git'));
+        await mkdir(join(gitPath, 'info')).catch((error) => {
+            if (error.code !== 'EEXIST')
+                throw error;
+        });
+        const info = await open(join(gitPath, 'info'), flags);
+        handles.push(info);
+        const exclude = join(pinned(info, join(root, '.git/info')), 'exclude');
+        const readable = await open(exclude, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK)
+            .catch((error) => { if (error.code === 'ENOENT')
+            return undefined; throw error; });
+        if (readable) {
+            try {
+                const stat = await readable.stat();
+                if (!stat.isFile() || stat.nlink !== 1 || stat.size > 1024 * 1024)
+                    throw new Error('invalid_git_exclude');
+                if ((await readable.readFile('utf8')).split('\n').some(line => line.trim() === ENTRY))
+                    return;
+            }
+            finally {
+                await readable.close();
+            }
+        }
+        file = await open(exclude, constants.O_RDWR | constants.O_CREAT | constants.O_APPEND | constants.O_NOFOLLOW | constants.O_NONBLOCK, 0o666);
+        const stat = await file.stat();
+        if (!stat.isFile() || stat.nlink !== 1 || stat.size > 1024 * 1024)
+            throw new Error('invalid_git_exclude');
+        const current = await file.readFile('utf8');
+        if (!current.split('\n').some(line => line.trim() === ENTRY)) {
+            await file.writeFile(`${current && !current.endsWith('\n') ? '\n' : ''}${ENTRY}\n`);
+        }
+    }
+    finally {
+        await file?.close();
+        for (const handle of handles.reverse())
+            await handle.close();
+    }
+}