@fungi.computer/truffle 0.1.1 → 0.2.1

package/dist/private-local-service-discovery.d.ts

@@ -1,38 +1,112 @@
 import { z } from "zod";
-declare const serviceRecordSchema: z.ZodObject<{
+export { sandboxStatusSchema } from "./private-local-sandbox.js";
+/**
+ * The client-service wire contract. Bump it with any change an older client
+ * cannot read; a running client then asks its window to restart.
+ */
+export declare const privateLocalServiceProtocol = 3;
+/** This build's identity: the packed CLI's content hash, or `source` for a source run. */
+export declare function privateLocalServiceVersion(): string;
+/**
+ * The fields every protocol keeps in `service.json`, so any client can
+ * identify, replace or stop a service whatever protocol it speaks.
+ */
+declare const serviceLifecycleSchema: z.ZodObject<{
+    protocol: z.ZodNumber;
+    version: z.ZodString;
     serviceId: z.ZodString & z.ZodType<import("@fungi.computer/cairn").CairnId<"local-service", "service", 1>, string, z.core.$ZodTypeInternals<import("@fungi.computer/cairn").CairnId<"local-service", "service", 1>, string>>;
+    pid: z.ZodNumber;
+    startedAt: z.ZodString;
+}, z.core.$loose>;
+declare const serviceRecordSchema: z.ZodObject<{
+    protocol: z.ZodLiteral<3>;
     baseUrl: z.ZodURL;
-}, z.core.$strict>;
-declare const serviceStatusSchema: z.ZodObject<{
+    version: z.ZodString;
     serviceId: z.ZodString & z.ZodType<import("@fungi.computer/cairn").CairnId<"local-service", "service", 1>, string, z.core.$ZodTypeInternals<import("@fungi.computer/cairn").CairnId<"local-service", "service", 1>, string>>;
-    baseUrl: z.ZodURL;
-    buildId: z.ZodOptional<z.ZodString>;
+    pid: z.ZodNumber;
+    startedAt: z.ZodString;
 }, z.core.$strict>;
 export type ServiceRecord = z.infer<typeof serviceRecordSchema>;
+/** Mandatory live diagnostics; never written into the registration pointer. */
+export declare const liveServiceStatusSchema: z.ZodObject<{
+    protocol: z.ZodLiteral<3>;
+    baseUrl: z.ZodURL;
+    version: z.ZodString;
+    serviceId: z.ZodString & z.ZodType<import("@fungi.computer/cairn").CairnId<"local-service", "service", 1>, string, z.core.$ZodTypeInternals<import("@fungi.computer/cairn").CairnId<"local-service", "service", 1>, string>>;
+    pid: z.ZodNumber;
+    startedAt: z.ZodString;
+    diagnostics: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        state: z.ZodLiteral<"active">;
+    }, z.core.$strict>, z.ZodObject<{
+        state: z.ZodLiteral<"failed">;
+        code: z.ZodEnum<{
+            "sink-open-failed": "sink-open-failed";
+            "sink-write-failed": "sink-write-failed";
+            "sink-close-failed": "sink-close-failed";
+        }>;
+        since: z.ZodISODateTime;
+    }, z.core.$strict>, z.ZodObject<{
+        state: z.ZodLiteral<"recovery-disabled">;
+        code: z.ZodEnum<{
+            "read-failed": "read-failed";
+            "decode-failed": "decode-failed";
+        }>;
+        since: z.ZodISODateTime;
+    }, z.core.$strict>], "state">;
+}, z.core.$strict>;
+export type LiveServiceStatus = z.infer<typeof liveServiceStatusSchema>;
+/**
+ * What `service.json` names: a service of this protocol, a service of another
+ * protocol (identified only by its lifecycle fields), or a file no protocol
+ * wrote.
+ */
+export type ServiceRegistration = Readonly<{
+    kind: "current";
+    record: ServiceRecord;
+}> | Readonly<{
+    kind: "other-protocol";
+    lifecycle: z.infer<typeof serviceLifecycleSchema>;
+}> | Readonly<{
+    kind: "unidentified";
+}>;
 export declare const selectionSchema: z.ZodObject<{
+    uiAttachmentLifetime: z.ZodOptional<z.ZodEnum<{
+        watch: "watch";
+        connection: "connection";
+    }>>;
     invocationRoot: z.ZodString;
     clientPath: z.ZodString;
+    requireSandbox: z.ZodOptional<z.ZodBoolean>;
     databasePath: z.ZodOptional<z.ZodString>;
     sessionId: z.ZodOptional<z.ZodString>;
     fungiMcp: z.ZodOptional<z.ZodObject<{
         endpoint: z.ZodPipe<z.ZodURL, z.ZodString>;
+        authentication: z.ZodOptional<z.ZodLiteral<"oyster-key">>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export declare const sessionCreationSchema: z.ZodObject<{
+    uiAttachmentLifetime: z.ZodOptional<z.ZodEnum<{
+        watch: "watch";
+        connection: "connection";
+    }>>;
     invocationRoot: z.ZodString;
     clientPath: z.ZodString;
+    requireSandbox: z.ZodOptional<z.ZodBoolean>;
     databasePath: z.ZodString;
     requestId: z.ZodString;
     fungiMcp: z.ZodOptional<z.ZodObject<{
         endpoint: z.ZodPipe<z.ZodURL, z.ZodString>;
+        authentication: z.ZodOptional<z.ZodLiteral<"oyster-key">>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export declare const sessionInspectionSchema: z.ZodObject<{
+    databasePath: z.ZodOptional<z.ZodString>;
+    invocationRoot: z.ZodString;
     fungiMcp: z.ZodOptional<z.ZodObject<{
         endpoint: z.ZodPipe<z.ZodURL, z.ZodString>;
+        authentication: z.ZodOptional<z.ZodLiteral<"oyster-key">>;
     }, z.core.$strict>>;
-    invocationRoot: z.ZodString;
-    databasePath: z.ZodOptional<z.ZodString>;
+    requireSandbox: z.ZodOptional<z.ZodBoolean>;
     sessionId: z.ZodString;
     limit: z.ZodNumber;
 }, z.core.$strict>;
@@ -40,11 +114,41 @@ export declare const selectedSchema: z.ZodObject<{
     agentId: z.ZodString;
     databasePath: z.ZodString;
     sessionId: z.ZodString;
-    routePath: z.ZodString;
+    routePath: z.ZodTemplateLiteral<`/agents/${string}`>;
+}, z.core.$strict>;
+export declare const discoverRequestSchema: z.ZodObject<{
+    invocationRoot: z.ZodString;
+    archived: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare const archiveRequestSchema: z.ZodObject<{
+    invocationRoot: z.ZodString;
+    agentId: z.ZodString;
+    archived: z.ZodBoolean;
+}, z.core.$strict>;
+/** The 409 answer to an archive the Local service refuses. */
+export declare const archiveRefusalSchema: z.ZodObject<{
+    code: z.ZodLiteral<"agent_archive_refused">;
+    reason: z.ZodEnum<{
+        pending: "pending";
+        running: "running";
+        archived: "archived";
+        not_creator: "not_creator";
+        self: "self";
+        unreadable: "unreadable";
+    }>;
+    error: z.ZodString;
 }, z.core.$strict>;
 export declare const sessionDiscoverySchema: z.ZodObject<{
     root: z.ZodString;
-    agentCount: z.ZodNumber;
+    agents: z.ZodArray<z.ZodObject<{
+        agentId: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        createdBy: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        unreadable: z.ZodOptional<z.ZodString>;
+        databasePath: z.ZodString;
+        sessionCount: z.ZodNumber;
+        updatedAt: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
     sessions: z.ZodArray<z.ZodObject<{
         databasePath: z.ZodString;
         sessionId: z.ZodString;
@@ -55,8 +159,8 @@ export declare const sessionDiscoverySchema: z.ZodObject<{
     problems: z.ZodArray<z.ZodObject<{
         kind: z.ZodEnum<{
             corrupt: "corrupt";
-            in_use: "in_use";
             unreadable: "unreadable";
+            in_use: "in_use";
         }>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
@@ -74,11 +178,18 @@ export declare const modelChoicesSchema: z.ZodArray<z.ZodObject<{
         max: "max";
     }>>;
 }, z.core.$strict>>;
+/** Resolve a read target without creating/chmodding a directory. */
+export declare function serviceDirectoryPath(directory?: string): string;
 export declare function serviceDirectory(directory?: string): Promise<string>;
 export declare const recordPath: (directory: string) => string;
+/** Read `service.json` by its lifecycle fields first, so any protocol's record is named. */
+export declare function readServiceRegistration(directory: string): Promise<ServiceRegistration | undefined>;
+/** The record of a service speaking this client's protocol, if one is registered. */
 export declare function readServiceRecord(directory: string): Promise<ServiceRecord | undefined>;
 /** An older listener must not erase its successor's discovery record. */
 export declare function removeOwnedServiceRecord(directory: string, serviceId: string): Promise<void>;
+/** Remove a `service.json` no protocol wrote; only call it once no owner is live. */
+export declare function removeUnidentifiedServiceRecord(directory: string): Promise<void>;
 /** Legacy owners have no SQLite lease, so their file lock must not be stolen. */
 export declare function assertNoUntrackedServiceOwner(directory: string): Promise<void>;
 /** Startup and shutdown serialize with the native listener and lifetime owner lock. */
@@ -87,10 +198,10 @@ export declare function acquireServiceLock(directory: string, name: "startup" |
  * Whether a service process holds this directory's lifetime lease. A held
  * lease is a live owner even when it is too busy to answer its handshake.
  */
-export declare function serviceOwnerIsLive(directory: string): boolean;
+export declare function serviceOwnerIsLive(directory: string): Promise<boolean>;
 export type ServiceProbe = Readonly<{
     kind: "running";
-    service: z.infer<typeof serviceStatusSchema>;
+    service: LiveServiceStatus;
 }> | Readonly<{
     kind: "not-running";
 }> | Readonly<{
@@ -98,4 +209,9 @@ export type ServiceProbe = Readonly<{
 }>;
 export declare function readLiveServiceStatus(record: ServiceRecord, timeoutMs?: number): Promise<ServiceProbe>;
 export declare function handshake(record: ServiceRecord): Promise<boolean>;
-export {};
+/**
+ * Clear the lifetime lock a killed owner left behind. The lease's process is
+ * gone, so acquiring the owner lock removes the marked directory;
+ * releasing it at once leaves nothing behind. A live owner makes this throw.
+ */
+export declare function clearAbandonedServiceOwner(directory: string): Promise<void>;

package/dist/private-local-service-discovery.js

@@ -1,4 +1,5 @@
-import { fungiMcpSelectionSchema } from "./private-fungi-mcp-selection.js";
+import { fungiMcpSelectionSchema } from "./private-fungi-mcp-selection-schema.js";
+import { localUiAttachmentLifetimeSchema } from "./private-local-ui-attachment.js";
 import { privateLocalExecPathSchema } from "./private-local-exec-path.js";
 import { chmod, mkdir, readFile, realpath, rm, rmdir, stat, writeFile, } from "node:fs/promises";
 import { join, resolve } from "node:path";
@@ -6,10 +7,43 @@ import { homedir } from "node:os";
 import lockfile from "proper-lockfile";
 import { z } from "zod";
 import { localServiceIds } from "./private-local-service-ids.js";
-import { acquireNodeStoreLease } from "@fungi.computer/shiitake/node";
-import { privateSqliteFailureCode } from "./private-sqlite-owner.js";
-const serviceRecordSchema = z.strictObject({
+import { acquireServiceOwnerLease, readServiceLeaseOwner, } from "./private-local-service-lease.js";
+import { modelReasoningLevels } from "@fungi.computer/shiitake/model-preference";
+import { archiveRefusalReasons } from "@fungi.computer/shiitake/agent-control";
+import { serviceDiagnosticsStatusSchema } from "./private-local-service-log.js";
+export { sandboxStatusSchema } from "./private-local-sandbox.js";
+/**
+ * The client-service wire contract. Bump it with any change an older client
+ * cannot read; a running client then asks its window to restart.
+ */
+export const privateLocalServiceProtocol = 3;
+/** This build's identity: the packed CLI's content hash, or `source` for a source run. */
+export function privateLocalServiceVersion() {
+    return (z
+        .string()
+        .regex(/^[a-f0-9]{64}$/u)
+        .optional()
+        .parse(process.env.FUNGI_BUNDLED_BUILD_ID) ?? "source");
+}
+/**
+ * The fields every protocol keeps in `service.json`, so any client can
+ * identify, replace or stop a service whatever protocol it speaks.
+ */
+const serviceLifecycleSchema = z.looseObject({
+    protocol: z.number().int().positive(),
+    version: z.string().min(1),
     serviceId: z.string().refine((value) => localServiceIds.service.is(value)),
+    /** The listener process. */
+    pid: z.number().int().positive(),
+    /**
+     * Pointer to the owner identity; signal authority comes from the lease row,
+     * not these file fields.
+     */
+    startedAt: z.string().min(1),
+});
+const serviceRecordSchema = z.strictObject({
+    ...serviceLifecycleSchema.shape,
+    protocol: z.literal(privateLocalServiceProtocol),
     baseUrl: z.url().refine((value) => {
         const url = new URL(value);
         return (url.protocol === "http:" &&
@@ -22,28 +56,30 @@ const serviceRecordSchema = z.strictObject({
             url.hash === "");
     }),
 });
-const serviceStatusSchema = serviceRecordSchema.safeExtend({
-    buildId: z
-        .string()
-        .regex(/^[a-f0-9]{64}$/u)
-        .optional(),
+/** Mandatory live diagnostics; never written into the registration pointer. */
+export const liveServiceStatusSchema = serviceRecordSchema.extend({
+    diagnostics: serviceDiagnosticsStatusSchema,
 });
 export const selectionSchema = z.strictObject({
+    uiAttachmentLifetime: localUiAttachmentLifetimeSchema.optional(),
     invocationRoot: z.string().min(1),
     clientPath: privateLocalExecPathSchema,
+    requireSandbox: z.boolean().optional(),
     databasePath: z.string().min(1).optional(),
     sessionId: z.string().min(1).optional(),
     fungiMcp: fungiMcpSelectionSchema.optional(),
 });
 export const sessionCreationSchema = z.strictObject({
+    uiAttachmentLifetime: localUiAttachmentLifetimeSchema.optional(),
     invocationRoot: z.string().min(1),
     clientPath: privateLocalExecPathSchema,
+    requireSandbox: z.boolean().optional(),
     databasePath: z.string().min(1),
     requestId: z.string().min(1),
     fungiMcp: fungiMcpSelectionSchema.optional(),
 });
 export const sessionInspectionSchema = selectionSchema
-    .omit({ clientPath: true })
+    .omit({ clientPath: true, uiAttachmentLifetime: true })
     .extend({
     sessionId: z.string().min(1),
     limit: z.number().int().min(1).max(200),
@@ -52,11 +88,34 @@ export const selectedSchema = z.strictObject({
     agentId: z.string().min(1),
     databasePath: z.string().min(1),
     sessionId: z.string().min(1),
-    routePath: z.string().regex(/^\/agents\/[0-9]+$/),
+    routePath: z.templateLiteral(["/agents/", z.uuid({ version: "v4" })]),
+});
+export const discoverRequestSchema = z.strictObject({
+    invocationRoot: z.string().min(1),
+    archived: z.boolean().default(false),
+});
+export const archiveRequestSchema = z.strictObject({
+    invocationRoot: z.string().min(1),
+    agentId: z.string().min(1),
+    archived: z.boolean(),
+});
+/** The 409 answer to an archive the Local service refuses. */
+export const archiveRefusalSchema = z.strictObject({
+    code: z.literal("agent_archive_refused"),
+    reason: z.enum(archiveRefusalReasons),
+    error: z.string(),
 });
 export const sessionDiscoverySchema = z.strictObject({
     root: z.string().min(1),
-    agentCount: z.number().int().nonnegative(),
+    agents: z.array(z.strictObject({
+        agentId: z.string().min(1),
+        name: z.string().optional(),
+        createdBy: z.string().nullable().optional(),
+        unreadable: z.string().optional(),
+        databasePath: z.string().min(1),
+        sessionCount: z.number().int().nonnegative(),
+        updatedAt: z.number().optional(),
+    })),
     sessions: z.array(z.strictObject({
         databasePath: z.string().min(1),
         sessionId: z.string().min(1),
@@ -66,41 +125,84 @@ export const sessionDiscoverySchema = z.strictObject({
     })),
     problems: z.array(z.strictObject({ kind: z.enum(["corrupt", "in_use", "unreadable"]) })),
 });
-const reasoningLevels = [
-    "minimal",
-    "low",
-    "medium",
-    "high",
-    "xhigh",
-    "max",
-];
 export const modelChoicesSchema = z.array(z.strictObject({
     providerId: z.string().min(1),
     providerName: z.string().min(1),
     id: z.string().min(1),
     name: z.string().min(1),
-    reasoning: z.array(z.enum(reasoningLevels)),
+    reasoning: z.array(z.enum(modelReasoningLevels)),
 }));
+/** Resolve a read target without creating/chmodding a directory. */
+export function serviceDirectoryPath(directory) {
+    return resolve(directory ?? join(homedir(), ".fungi", "service"));
+}
 export async function serviceDirectory(directory) {
-    const path = resolve(directory ?? join(homedir(), ".fungi", "service"));
+    const path = serviceDirectoryPath(directory);
     await mkdir(path, { recursive: true, mode: 0o700 });
     await chmod(path, 0o700);
     return realpath(path);
 }
 export const recordPath = (directory) => join(directory, "service.json");
-export async function readServiceRecord(directory) {
+/** Read `service.json` by its lifecycle fields first, so any protocol's record is named. */
+export async function readServiceRegistration(directory) {
+    let text;
     try {
-        return serviceRecordSchema.parse(JSON.parse(await readFile(recordPath(directory), "utf8")));
+        text = await readFile(recordPath(directory), "utf8");
     }
     catch (cause) {
         if (cause instanceof Error && "code" in cause && cause.code === "ENOENT")
             return undefined;
         throw cause;
     }
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch (cause) {
+        if (cause instanceof SyntaxError)
+            return { kind: "unidentified" };
+        throw cause;
+    }
+    const lifecycle = serviceLifecycleSchema.safeParse(json);
+    if (!lifecycle.success) {
+        // A service from before the PID was recorded cannot be signalled; name it
+        // and its own stop route instead of treating it as unidentified.
+        const older = serviceRecordSchema
+            .pick({ serviceId: true, baseUrl: true })
+            .safeParse(json);
+        if (older.success)
+            throw new LocalServiceRecordWithoutPid(directory, older.data);
+        return { kind: "unidentified" };
+    }
+    if (lifecycle.data.protocol !== privateLocalServiceProtocol)
+        return { kind: "other-protocol", lifecycle: lifecycle.data };
+    return { kind: "current", record: serviceRecordSchema.parse(json) };
+}
+/** `service.json` was written by a service too old to record its PID. */
+class LocalServiceRecordWithoutPid extends Error {
+    name = "LocalServiceRecordWithoutPid";
+    constructor(directory, service) {
+        const stopUrl = new URL(`/service/${service.serviceId}/stop`, service.baseUrl);
+        super(`An older Fungi service (${service.serviceId} on port ${new URL(service.baseUrl).port}) is registered in ${recordPath(directory)}, and this fungi cannot stop it. Stop it with \`curl -X POST ${stopUrl.href}\`; if it keeps running, end the process whose command line contains \`--internal-service ${directory}\`. If it is no longer running, delete ${recordPath(directory)}. Then retry; saved Sessions are kept.`);
+    }
+}
+/** The record of a service speaking this client's protocol, if one is registered. */
+export async function readServiceRecord(directory) {
+    const registration = await readServiceRegistration(directory);
+    return registration?.kind === "current" ? registration.record : undefined;
 }
 /** An older listener must not erase its successor's discovery record. */
 export async function removeOwnedServiceRecord(directory, serviceId) {
-    if ((await readServiceRecord(directory))?.serviceId === serviceId)
+    const registration = await readServiceRegistration(directory);
+    if ((registration?.kind === "current" &&
+        registration.record.serviceId === serviceId) ||
+        (registration?.kind === "other-protocol" &&
+            registration.lifecycle.serviceId === serviceId))
+        await rm(recordPath(directory), { force: true });
+}
+/** Remove a `service.json` no protocol wrote; only call it once no owner is live. */
+export async function removeUnidentifiedServiceRecord(directory) {
+    if ((await readServiceRegistration(directory))?.kind === "unidentified")
         await rm(recordPath(directory), { force: true });
 }
 const ownerLeaseMarker = (directory) => join(directory, "owner.lock", "sqlite-owner");
@@ -132,16 +234,13 @@ export async function acquireServiceLock(directory, name) {
                 throw error;
             },
         });
-    // The SQLite lease is the lifetime guard. proper-lockfile cannot heartbeat
-    // a directory containing the marker: writing the marker changes its mtime
-    // and makes its own heartbeat declare the live lock compromised.
-    const lease = acquireNodeStoreLease(join(directory, "owner.sqlite"));
+    const releaseLease = await acquireServiceOwnerLease(directory);
     const lockPath = join(directory, "owner.lock");
     let created = false;
     try {
         await assertNoUntrackedServiceOwner(directory);
-        // A dead updated owner can leave a marked directory behind. The SQLite
-        // lease is already free, so removing it does not trust a heartbeat.
+        // A dead owner can leave a marked directory behind. Its process claim has
+        // already been replaced transactionally, without trusting a heartbeat.
         if (await pathExists(ownerLeaseMarker(directory)))
             await rm(lockPath, { recursive: true });
         await mkdir(lockPath);
@@ -157,7 +256,7 @@ export async function acquireServiceLock(directory, name) {
                 await rm(lockPath, { recursive: true });
         }
         finally {
-            lease.release();
+            releaseLease();
         }
         throw cause;
     }
@@ -167,7 +266,7 @@ export async function acquireServiceLock(directory, name) {
             await rmdir(lockPath);
         }
         finally {
-            lease.release();
+            releaseLease();
         }
     };
 }
@@ -175,18 +274,8 @@ export async function acquireServiceLock(directory, name) {
  * Whether a service process holds this directory's lifetime lease. A held
  * lease is a live owner even when it is too busy to answer its handshake.
  */
-export function serviceOwnerIsLive(directory) {
-    let lease;
-    try {
-        lease = acquireNodeStoreLease(join(directory, "owner.sqlite"));
-    }
-    catch (cause) {
-        if (privateSqliteFailureCode(cause) === "busy")
-            return true;
-        throw cause;
-    }
-    lease.release();
-    return false;
+export async function serviceOwnerIsLive(directory) {
+    return (await readServiceLeaseOwner(directory)) !== undefined;
 }
 const transportFailureSchema = z.looseObject({
     code: z.string().optional(),
@@ -200,9 +289,12 @@ export async function readLiveServiceStatus(record, timeoutMs = 2000) {
         });
         if (!response.ok)
             return { kind: "unavailable" };
-        const actual = serviceStatusSchema.parse(await response.json());
+        const actual = liveServiceStatusSchema.parse(await response.json());
         return actual.serviceId === record.serviceId &&
-            actual.baseUrl === record.baseUrl
+            actual.baseUrl === record.baseUrl &&
+            actual.pid === record.pid &&
+            actual.startedAt === record.startedAt &&
+            actual.version === record.version
             ? { kind: "running", service: actual }
             : { kind: "unavailable" };
     }
@@ -219,3 +311,12 @@ export async function readLiveServiceStatus(record, timeoutMs = 2000) {
 export async function handshake(record) {
     return (await readLiveServiceStatus(record)).kind === "running";
 }
+/**
+ * Clear the lifetime lock a killed owner left behind. The lease's process is
+ * gone, so acquiring the owner lock removes the marked directory;
+ * releasing it at once leaves nothing behind. A live owner makes this throw.
+ */
+export async function clearAbandonedServiceOwner(directory) {
+    const release = await acquireServiceLock(directory, "owner");
+    await release();
+}

package/dist/private-local-service-lease.d.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+declare const ownerSchema: z.ZodObject<{
+    pid: z.ZodNumber;
+    startedAt: z.ZodString;
+}, z.core.$strip>;
+export type ServiceLeaseOwner = z.infer<typeof ownerSchema>;
+/** The live claim's identity comes from SQLite, never from service.json. */
+export declare function readServiceLeaseOwner(directory: string): Promise<ServiceLeaseOwner | undefined>;
+/**
+ * Acquire the one process-owned row and publish its identity in the same
+ * transaction. This is a process-lifetime claim, not a heartbeat/timeout lease:
+ * only release or proof that the recorded process is gone permits replacement.
+ * Committing makes the identity readable by clients while the owner runs.
+ */
+export declare function acquireServiceOwnerLease(directory: string): Promise<() => void>;
+export {};

package/dist/private-local-service-lease.js

@@ -0,0 +1,105 @@
+import { openPrivateWritableSqliteDatabase, } from "./private-sqlite-owner.js";
+import { join } from "node:path";
+import { z } from "zod";
+import { readOwnProcessStart, readProcessStart, } from "./private-local-process-identity.js";
+const ownerSchema = z.object({
+    pid: z.number().int().positive(),
+    startedAt: z.string().min(1),
+});
+function openLease(directory) {
+    const database = openPrivateWritableSqliteDatabase(join(directory, "owner.sqlite"), 0);
+    try {
+        database.exec("CREATE TABLE IF NOT EXISTS service_owner (id INTEGER PRIMARY KEY CHECK (id = 1), pid INTEGER NOT NULL, startedAt TEXT NOT NULL)");
+        return database;
+    }
+    catch (cause) {
+        database.close();
+        throw cause;
+    }
+}
+function readOwner(database) {
+    const row = database
+        .prepare("SELECT pid, startedAt FROM service_owner WHERE id = 1")
+        .get();
+    return row === undefined ? undefined : ownerSchema.parse(row);
+}
+async function ownerIsLive(owner) {
+    const current = await readProcessStart(owner.pid);
+    if (current.kind !== "unverifiable")
+        return current.kind === "running" && current.start === owner.startedAt;
+    // Without precise identity we may retain a stale claim, but never steal a
+    // possibly live one. Signal 0 checks existence; it does not terminate it.
+    try {
+        process.kill(owner.pid, 0);
+        return true;
+    }
+    catch (cause) {
+        if (cause instanceof Error && "code" in cause) {
+            if (cause.code === "ESRCH")
+                return false;
+            if (cause.code === "EPERM")
+                return true;
+        }
+        throw cause;
+    }
+}
+/** The live claim's identity comes from SQLite, never from service.json. */
+export async function readServiceLeaseOwner(directory) {
+    const database = openLease(directory);
+    try {
+        const owner = readOwner(database);
+        return owner !== undefined && (await ownerIsLive(owner))
+            ? owner
+            : undefined;
+    }
+    finally {
+        database.close();
+    }
+}
+/**
+ * Acquire the one process-owned row and publish its identity in the same
+ * transaction. This is a process-lifetime claim, not a heartbeat/timeout lease:
+ * only release or proof that the recorded process is gone permits replacement.
+ * Committing makes the identity readable by clients while the owner runs.
+ */
+export async function acquireServiceOwnerLease(directory) {
+    const own = { pid: process.pid, startedAt: await readOwnProcessStart() };
+    const database = openLease(directory);
+    let transaction = false;
+    try {
+        database.exec("BEGIN IMMEDIATE");
+        transaction = true;
+        const owner = readOwner(database);
+        if (owner !== undefined && (await ownerIsLive(owner)))
+            throw new Error("The Fungi service owner database is locked by a live process");
+        database
+            .prepare("INSERT OR REPLACE INTO service_owner (id, pid, startedAt) VALUES (1, ?, ?)")
+            .run(own.pid, own.startedAt);
+        database.exec("COMMIT");
+        transaction = false;
+    }
+    finally {
+        try {
+            if (transaction)
+                database.exec("ROLLBACK");
+        }
+        finally {
+            database.close();
+        }
+    }
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        const database = openLease(directory);
+        try {
+            database
+                .prepare("DELETE FROM service_owner WHERE id = 1 AND pid = ? AND startedAt = ?")
+                .run(own.pid, own.startedAt);
+            released = true;
+        }
+        finally {
+            database.close();
+        }
+    };
+}

package/dist/private-local-service-listener.d.ts

@@ -1,15 +1,22 @@
+import { type ServiceDrainPhase } from "./private-local-service-log.js";
 import { runLocalAuthCli } from "./auth-cli.js";
+import { type PrivateLocalConfigRoot } from "./private-local-config-root.js";
 import { listPrivateModels } from "./local-models.js";
 import { type OpenLocalServiceRuntime } from "./private-local-service-owner.js";
 export declare function createPrivateLocalServiceShutdown(input: {
     closeOwners: () => Promise<void>;
     closeServer: () => Promise<void>;
+    closeDiagnostics?: () => void;
     removeRecord: () => Promise<void>;
     releaseOwner: () => Promise<void>;
 }): {
-    drain: () => Promise<void>;
     finish: () => Promise<void>;
     isDraining: () => boolean;
+    phase: () => ServiceDrainPhase;
 };
 /** Native Bun listener retained from TUI; service owns both listener and stores. */
-export declare function runPrivateLocalService(directory: string, openRuntime?: OpenLocalServiceRuntime, listModels?: typeof listPrivateModels, runAuth?: typeof runLocalAuthCli): Promise<void>;
+export declare function runPrivateLocalService(directory: string, openRuntime?: OpenLocalServiceRuntime, listModels?: typeof listPrivateModels, runAuth?: typeof runLocalAuthCli, 
+/** How often the service releases Agents nothing uses. */
+idleSweepMs?: number, 
+/** Narrow manifest I/O port, independent of the Agent-runtime opener. */
+readRecoveryManifest?: (path: string) => Promise<string>, root?: PrivateLocalConfigRoot): Promise<void>;