@fungi.computer/computer 0.0.1 → 0.2.0

package/README.md

@@ -13,6 +13,13 @@ from `@fungi.computer/computer/fleet/wire`, and backing descriptions from
 declarations. The `./fleet` lifecycle and main Computer entry require the host
 runtime's Cloudflare Workers types.
 
+The packed stranger check exercises these Node-safe entries and the egress
+helpers after a cold install of the runtime closure. The fork's companion check
+parses the published shell-module groups used by the Computer image with Acorn
+and checks their declarations. Neither check starts a Computer, executes a
+Worker shell, or qualifies the Worker/Workspace/Git SDK in a Node type
+environment.
+
 `@fungi.computer/computer/fleet` owns the host-neutral grant check, backing
 records and fact contracts. A host authenticates its caller and supplies a
 `ComputerGrant`: one Computer, explicit actions, an expiry, optional host-owned
@@ -82,11 +89,11 @@ publish an App or replace a production Computer image.
 SQLite provider. Files belong to that workspace, not to a running shell process.
 A file read can work with no available execution backend.
 
-[Operation contracts](src/operation-contract.ts) declare discovery, bounded file
-reads/writes, directories, command execution, processes and port exposure. The
-[Files adapter](src/files.ts) implements the same read and compare/replace
-contract for Agent tools. Failed containment, conflicting contents and reserved
-ports remain explicit errors.
+[Operation contracts](../computer-contract/README.md), in their own package,
+declare discovery, bounded file reads/writes, directories, command execution,
+processes and port exposure. The [Files adapter](src/files.ts) implements the
+same read and compare/replace contract for Agent tools. Failed containment,
+conflicting contents and reserved ports remain explicit errors.
 
 An execution request carries a replay key. The
 [operation record](src/operation-record.ts) admits the immutable input and
@@ -130,6 +137,27 @@ registered host to the Workspace backend interface. Platform containers use the
 maintained Cloudflare container backend. Neither backend label nor a green
 container fixture certifies an installed VM host or production routing.
 
+Local dial verification binds Seam's replay-admission port to the existing
+Computer Durable Object's SQLite database. That database is the receiver
+namespace across reconstruction, shared by its attached devices; nonce identity
+inside it is nonce-only. One native transaction prunes only strictly expired
+records, refuses duplicates or the private 4,096-record ceiling, and commits the
+nonce before admission succeeds. Seam owns the inclusive retention deadline;
+duplicates never renew it and capacity never evicts live history. Storage
+failure refuses admission without a process-local fallback. Attachment,
+device-key, signature, audience and revocation authority remain unchanged.
+
+`createLocalBackendReplayStore(owner)` is exported for another native Local-dial
+receiver that uses its own existing SQLite owner, including a Team machine-link
+receiver. The caller owns pins, audience, membership and revocation; this store
+owns only atomic, bounded nonce retention. It neither creates a Computer nor
+shares nonce history across separate databases.
+
+`test:unit` includes the `machine-link-reopen-replay` proof: two physical Node
+processes call the actual local-dial verifier against the same SQLite file. This
+proves reconstructed-process replay refusal, not a complete HTTP/WebSocket
+route, deployed host or container-health acceptance.
+
 ## Processes, ports and lifetime
 
 Start requires a host-owned opaque `requestId` and `requestScope`, plus a
@@ -196,11 +224,11 @@ were saved in a hosted Computer. Do not copy its temporary output into source.
 ## Proof and reference
 
 [package.json](package.json) declares the private entrypoints `.` and `./files`,
-`./backing`, `./host-config`, `./operations`.
-[Runtime proof](test/runtime-proof.mjs) checks native workspace operations and
-reconstruction. [Process proof](test/process-proof.mjs) checks retained process
-identity against the real container.
-[Terminal proof](test/terminal-container-proof.mjs),
+`./backing`, `./host-config`. Operation schemas come from
+`@fungi.computer/computer-contract`. [Runtime proof](test/runtime-proof.mjs)
+checks native workspace operations and reconstruction.
+[Process proof](test/process-proof.mjs) checks retained process identity against
+the real container. [Terminal proof](test/terminal-container-proof.mjs),
 [resource proof](test/container-resource-proof.mjs) and
 [backend tests](test/computer-backends.test.mjs) cover their separate
 boundaries. The declared nightly egress proof is separate from the ordinary

package/dist/computer-backends.d.ts

@@ -4,7 +4,7 @@ export declare const hostedBackingSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"platform-container">;
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"on-box-vm">;
-    hostId: z.ZodString;
+    hostId: z.ZodLazy<z.ZodString>;
 }, z.core.$strict>], "kind">;
 export type HostedBacking = z.infer<typeof hostedBackingSchema>;
 /** A member's machine, attached with a device key that never leaves it. */
@@ -12,39 +12,38 @@ export declare const localBackendSchema: z.ZodObject<{
     kind: z.ZodLiteral<"local">;
     deviceId: z.ZodString;
     publicKey: z.ZodBase64;
-    hostLabel: z.ZodString;
-    folderLabel: z.ZodString;
+    hostLabel: z.ZodLazy<z.ZodString>;
+    folderLabel: z.ZodLazy<z.ZodString>;
 }, z.core.$strict>;
 export type LocalBackend = z.infer<typeof localBackendSchema>;
 export declare const attachedBackendSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"platform-container">;
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"on-box-vm">;
-    hostId: z.ZodString;
+    hostId: z.ZodLazy<z.ZodString>;
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"local">;
     deviceId: z.ZodString;
     publicKey: z.ZodBase64;
-    hostLabel: z.ZodString;
-    folderLabel: z.ZodString;
+    hostLabel: z.ZodLazy<z.ZodString>;
+    folderLabel: z.ZodLazy<z.ZodString>;
 }, z.core.$strict>], "kind">;
 export type AttachedBackend = z.infer<typeof attachedBackendSchema>;
 /** The stable Workspace backend id: its sync cursor is keyed by it. */
 export declare function attachedBackendId(backend: AttachedBackend): string;
 /** One Computer's attached backends, in attach order; ids are unique. */
-export declare const attachedBackendsSchema: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+export declare const attachedBackendsSchema: z.ZodLazy<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"platform-container">;
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"on-box-vm">;
-    hostId: z.ZodString;
+    hostId: z.ZodLazy<z.ZodString>;
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"local">;
     deviceId: z.ZodString;
     publicKey: z.ZodBase64;
-    hostLabel: z.ZodString;
-    folderLabel: z.ZodString;
-}, z.core.$strict>], "kind">>;
-export declare const attachedBackendIdSchema: z.ZodString;
+    hostLabel: z.ZodLazy<z.ZodString>;
+    folderLabel: z.ZodLazy<z.ZodString>;
+}, z.core.$strict>], "kind">>>;
 export type AttachedBackendStatus = "ready" | "online" | "offline";
 /** What a Computer reports about one attached backend. */
 export type AttachedBackendView = Readonly<{

package/dist/computer-backends.js

@@ -8,8 +8,8 @@ import * as z from "zod";
  * id at most; a local backend carries its device's public key and two display
  * labels, never a path on the member's machine.
  */
-const hostIdSchema = z.string().regex(/^[a-z0-9][a-z0-9-]{0,62}$/);
-const labelSchema = z.string().trim().min(1).max(256);
+const hostIdSchema = z.lazy(() => z.string().regex(/^[a-z0-9][a-z0-9-]{0,62}$/));
+const labelSchema = z.lazy(() => z.string().trim().min(1).max(256));
 /** A backend the platform runs: a Cloudflare container or an on-box VM. */
 export const hostedBackingSchema = z.discriminatedUnion("kind", [
     z.strictObject({ kind: z.literal("platform-container") }),
@@ -40,13 +40,10 @@ export function attachedBackendId(backend) {
     }
 }
 /** One Computer's attached backends, in attach order; ids are unique. */
-export const attachedBackendsSchema = z
+export const attachedBackendsSchema = z.lazy(() => z
     .array(attachedBackendSchema)
     .max(16)
-    .refine((backends) => new Set(backends.map(attachedBackendId)).size === backends.length, "attached backend ids must be unique");
-export const attachedBackendIdSchema = z
-    .string()
-    .regex(/^(container|vm-[a-z0-9][a-z0-9-]{0,62}|local-[a-z2-7]{16})$/);
+    .refine((backends) => new Set(backends.map(attachedBackendId)).size === backends.length, "attached backend ids must be unique"));
 export function describeAttachedBackend(backend, online) {
     const id = attachedBackendId(backend);
     switch (backend.kind) {

package/dist/exec-output.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Keep one command stream within `maximumStreamBytes`. A cut stream ends with
+ * a visible marker line (counted inside the bound, excluded from the totals)
+ * and reports a typed entry.
+ */
+export declare function boundExecStream(value: string, stream: "stdout" | "stderr"): {
+    value: string;
+    truncation: readonly {
+        stream: "stdout" | "stderr";
+        keptBytes: number;
+        totalBytes: number;
+    }[];
+};

package/dist/exec-output.js

@@ -0,0 +1,24 @@
+import { execTruncationMarker, maximumStreamBytes, truncationMarkerReserveBytes, utf8Prefix, } from "@fungi.computer/computer-contract";
+const utf8 = new TextEncoder();
+const noTruncation = [];
+/**
+ * Keep one command stream within `maximumStreamBytes`. A cut stream ends with
+ * a visible marker line (counted inside the bound, excluded from the totals)
+ * and reports a typed entry.
+ */
+export function boundExecStream(value, stream) {
+    const bytes = utf8.encode(value);
+    if (bytes.byteLength <= maximumStreamBytes) {
+        return { value, truncation: noTruncation };
+    }
+    const kept = utf8Prefix(bytes, maximumStreamBytes - truncationMarkerReserveBytes);
+    const entry = {
+        stream,
+        keptBytes: kept.byteLength,
+        totalBytes: bytes.byteLength,
+    };
+    return {
+        value: `${new TextDecoder().decode(kept)}${execTruncationMarker(entry)}`,
+        truncation: [entry],
+    };
+}

package/dist/execution-lifecycle.d.ts

@@ -0,0 +1,35 @@
+import { type ComputerExecutionCloseReason, type ComputerExecutionInvocation, type ComputerValue } from "@fungi.computer/computer-contract";
+type ExecutionStorage = Pick<DurableObjectStorage, "sql" | "transactionSync">;
+type Phase = "opening" | "dispatching" | "open" | "closed";
+type ComputerExecutionRecord = Readonly<{
+    invocation: ComputerExecutionInvocation;
+    phase: Phase;
+    backend: string;
+    nativeOpened: boolean;
+    closeReason: ComputerExecutionCloseReason | null;
+    context: ComputerValue;
+}>;
+/**
+ * Only public host context and native invocation identity are durable here.
+ * The operation/process owners continue to own admission, replay and retention;
+ * neither credentials nor a second process inventory belong in this table.
+ */
+declare class ComputerExecutionLifecycle {
+    #private;
+    readonly reconstructed: readonly ComputerExecutionRecord[];
+    constructor(storage: ExecutionStorage);
+    get(id: string): ComputerExecutionRecord | undefined;
+    /** Called synchronously after the existing owner's atomic NEW admission. */
+    begin(invocation: ComputerExecutionInvocation, backend: string, context: ComputerValue): void;
+    /** The last synchronous fence before invoking the maintained native SDK. */
+    dispatch(id: string): void;
+    /** A native handle arrived; this phase alone is not proof of native liveness. */
+    opened(id: string): void;
+    /** Persist revocation before the caller attempts the remote host callback. */
+    close(id: string, reason: ComputerExecutionCloseReason): ComputerExecutionRecord | undefined;
+    /** Closed metadata cannot outlive the existing operation/process owner. */
+    prune(): void;
+}
+/** Construct the ComputerDO's internal lifecycle owner, not a package API. */
+export declare function createComputerExecutionLifecycle(storage: Pick<DurableObjectStorage, "sql" | "transactionSync">): ComputerExecutionLifecycle;
+export {};

package/dist/execution-lifecycle.js

@@ -0,0 +1,78 @@
+import { computerValueSchema, } from "@fungi.computer/computer-contract";
+function record(row) {
+    return {
+        invocation: { id: row.id, kind: row.kind },
+        phase: row.phase,
+        backend: row.backend,
+        nativeOpened: row.native_opened === 1,
+        closeReason: row.close_reason,
+        context: computerValueSchema.parse(JSON.parse(row.context_json)),
+    };
+}
+/**
+ * Only public host context and native invocation identity are durable here.
+ * The operation/process owners continue to own admission, replay and retention;
+ * neither credentials nor a second process inventory belong in this table.
+ */
+class ComputerExecutionLifecycle {
+    #storage;
+    reconstructed;
+    constructor(storage) {
+        this.#storage = storage;
+        this.reconstructed = storage.transactionSync(() => {
+            // The first partial checkpoint's preview metadata is disposable. Keep
+            // only this current representation, never an old-shape reader or copy.
+            storage.sql.exec("DROP TABLE IF EXISTS computer_execution_lifecycle");
+            storage.sql.exec("CREATE TABLE IF NOT EXISTS computer_execution_invocations (id TEXT PRIMARY KEY, kind TEXT NOT NULL CHECK (kind IN ('exec', 'process')), phase TEXT NOT NULL CHECK (phase IN ('opening', 'dispatching', 'open', 'closed')), backend TEXT NOT NULL, native_opened INTEGER NOT NULL DEFAULT 0 CHECK (native_opened IN (0, 1)), context_json TEXT NOT NULL, close_reason TEXT CHECK (close_reason IN ('refused_start', 'native_exit', 'unknown', 'reconstructed'))) STRICT");
+            const interrupted = storage.sql
+                .exec("SELECT id, kind, phase, backend, native_opened, context_json, close_reason FROM computer_execution_invocations WHERE phase <> 'closed' AND (kind = 'exec' OR phase = 'opening')")
+                .toArray()
+                .map(record);
+            // A cold exec never probes or dispatches again. Process reconciliation
+            // will require native proof; an unfinished issuer open has no such proof.
+            storage.sql.exec("UPDATE computer_execution_invocations SET phase = 'closed', close_reason = 'reconstructed' WHERE phase <> 'closed' AND (kind = 'exec' OR phase = 'opening')");
+            return interrupted;
+        });
+        this.prune();
+    }
+    get(id) {
+        const row = this.#storage.sql
+            .exec("SELECT id, kind, phase, backend, native_opened, context_json, close_reason FROM computer_execution_invocations WHERE id = ?", id)
+            .toArray()[0];
+        return row === undefined ? undefined : record(row);
+    }
+    /** Called synchronously after the existing owner's atomic NEW admission. */
+    begin(invocation, backend, context) {
+        const publicContext = computerValueSchema.parse(context);
+        this.prune();
+        this.#storage.sql.exec("INSERT INTO computer_execution_invocations (id, kind, phase, backend, context_json) VALUES (?, ?, 'opening', ?, ?)", invocation.id, invocation.kind, backend, JSON.stringify(publicContext));
+    }
+    /** The last synchronous fence before invoking the maintained native SDK. */
+    dispatch(id) {
+        if (this.get(id)?.phase !== "opening")
+            throw new Error("Computer execution is no longer open for dispatch");
+        this.#storage.sql.exec("UPDATE computer_execution_invocations SET phase = 'dispatching' WHERE id = ?", id);
+    }
+    /** A native handle arrived; this phase alone is not proof of native liveness. */
+    opened(id) {
+        this.#storage.sql.exec("UPDATE computer_execution_invocations SET native_opened = 1, phase = CASE WHEN phase = 'dispatching' THEN 'open' ELSE phase END WHERE id = ?", id);
+    }
+    /** Persist revocation before the caller attempts the remote host callback. */
+    close(id, reason) {
+        return this.#storage.transactionSync(() => {
+            const current = this.get(id);
+            if (current === undefined || current.phase === "closed")
+                return undefined;
+            this.#storage.sql.exec("UPDATE computer_execution_invocations SET phase = 'closed', close_reason = ? WHERE id = ?", reason, id);
+            return current;
+        });
+    }
+    /** Closed metadata cannot outlive the existing operation/process owner. */
+    prune() {
+        this.#storage.sql.exec("DELETE FROM computer_execution_invocations WHERE phase = 'closed' AND ((kind = 'exec' AND NOT EXISTS (SELECT 1 FROM computer_operations WHERE 'exec:' || request_id = computer_execution_invocations.id)) OR (kind = 'process' AND NOT EXISTS (SELECT 1 FROM computer_processes WHERE id = computer_execution_invocations.id)))");
+    }
+}
+/** Construct the ComputerDO's internal lifecycle owner, not a package API. */
+export function createComputerExecutionLifecycle(storage) {
+    return new ComputerExecutionLifecycle(storage);
+}

package/dist/files-patch.d.ts

@@ -3,17 +3,25 @@ import type { Workspace } from "@fungi.computer/cloudflare-computer";
 export declare function applyWorkspacePatch(workspace: Pick<Workspace, "runtime">, backend: string, input: {
     patch: string;
 }): Promise<{
-    status: "completed" | "failed" | "cancelled";
+    status: "failed" | "completed" | "cancelled";
     exitCode: number;
     stdout: string;
     stderr: string;
-    truncated: boolean;
+    truncated: false | {
+        stream: "stdout" | "stderr";
+        keptBytes: number;
+        totalBytes: number;
+    }[];
 } | {
-    status: "completed" | "failed" | "cancelled";
+    status: "failed" | "completed" | "cancelled";
     exitCode: number;
     stdout: string;
     stderr: string;
-    truncated: boolean;
+    truncated: false | {
+        stream: "stdout" | "stderr";
+        keptBytes: number;
+        totalBytes: number;
+    }[];
     error: {
         kind: "mismatch";
     };

package/dist/files-patch.js

@@ -50,7 +50,8 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     var e = new Error(message);
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
-import { patchInputSchema, patchOutputSchema, maximumStreamBytes, } from "./operation-contract.js";
+import { patchInputSchema, patchOutputSchema, } from "@fungi.computer/computer-contract";
+import { boundExecStream } from "./exec-output.js";
 /** The packaged, pinned Codex engine owns patch parsing and the Workspace jail. */
 const nativePatch = {
     executable: "/opt/fungi/fungi-apply-patch",
@@ -58,15 +59,6 @@ const nativePatch = {
     timeoutMs: 30_000,
     mismatchExitCode: 23,
 };
-function bounded(value) {
-    const bytes = new TextEncoder().encode(value);
-    return bytes.length <= maximumStreamBytes
-        ? { value, truncated: false }
-        : {
-            value: new TextDecoder().decode(bytes.slice(0, maximumStreamBytes)),
-            truncated: true,
-        };
-}
 /** Await Workspace synchronization even when the native engine reports a partial failure. */
 export async function applyWorkspacePatch(workspace, backend, input) {
     const env_1 = { stack: [], error: void 0, hasError: false };
@@ -81,10 +73,10 @@ export async function applyWorkspacePatch(workspace, backend, input) {
         }), false);
         const result = await run.result();
         const synchronizationFailure = result.sync.status === "pending" ? result.sync.error : null;
-        const stdout = bounded(result.stdout);
-        const stderr = bounded(synchronizationFailure !== null
+        const stdout = boundExecStream(result.stdout, "stdout");
+        const stderr = boundExecStream(synchronizationFailure !== null
             ? `${result.stderr}\nPatch filesystem synchronization failed: ${synchronizationFailure}. Earlier patch writes may remain.`
-            : result.stderr);
+            : result.stderr, "stderr");
         const output = {
             status: synchronizationFailure !== null ? "failed" : result.status,
             exitCode: synchronizationFailure !== null && result.exitCode === 0
@@ -92,7 +84,9 @@ export async function applyWorkspacePatch(workspace, backend, input) {
                 : result.exitCode,
             stdout: stdout.value,
             stderr: stderr.value,
-            truncated: stdout.truncated || stderr.truncated,
+            truncated: stdout.truncation.length + stderr.truncation.length === 0
+                ? false
+                : [...stdout.truncation, ...stderr.truncation],
         };
         return patchOutputSchema.parse(result.exitCode === nativePatch.mismatchExitCode
             ? { ...output, error: { kind: "mismatch" } }

package/dist/files.d.ts

@@ -1,7 +1,8 @@
 import type { SQLiteWorkspaceProvider, WorkspaceClient } from "@fungi.computer/cloudflare-computer";
 /** Files need only the Workspace filesystem, local or leased through a stub. */
 export type WorkspaceFiles = Pick<WorkspaceClient, "fs">;
-import { type ComputerFileReplacement, type ComputerFileReplacementResult } from "./operation-contract.js";
+import type { FilesPort } from "@fungi.computer/knapsack";
+import { type ComputerFileGlobInput, type ComputerFileGrepInput, type ComputerFileListInput, type ComputerFileReplacement, type ComputerFileReplacementResult } from "@fungi.computer/computer-contract";
 export type WorkspaceFilesOwner = Readonly<{
     replaceFileIfUnchanged: (input: ComputerFileReplacement) => Promise<ComputerFileReplacementResult>;
 }>;
@@ -15,11 +16,48 @@ export declare function decodeUtf8Page(bytes: Uint8Array, path: string, moreByte
 export declare function readBoundedWorkspaceText(provider: SQLiteWorkspaceProvider, path: string, maximumBytes: number): string;
 /** Adapt native Workspace.fs at the one real file boundary. */
 export declare function createWorkspaceFilesPort(workspace: WorkspaceFiles, owner: WorkspaceFilesOwner): Readonly<{
+    rest: Readonly<{
+        list: (input: ComputerFileListInput) => Promise<{
+            path: string;
+            entries: {
+                name: string;
+                size: number;
+                modifiedAt: number;
+                type: "file" | "directory" | "symlink";
+            }[];
+            nextOffset: number | null;
+        }>;
+        glob(input: ComputerFileGlobInput): Promise<{
+            path: string;
+            matches: string[];
+            truncated: boolean;
+        }>;
+        grep(input: ComputerFileGrepInput): Promise<{
+            path: string;
+            matches: {
+                path: string;
+                line: number;
+                text: string;
+            }[];
+            truncated: boolean;
+        }>;
+    }>;
     read(input: {
         path: string;
         offset: number;
         limit: number;
     }): Promise<{
+        path: string;
+        image: {
+            mimeType: "image/png" | "image/jpeg" | "image/gif" | "image/webp";
+            data: string;
+            bytes: number;
+        };
+        file?: {
+            computerId: string;
+            path: string;
+        };
+    } | {
         path: string;
         content: string;
         offset: number;
@@ -29,25 +67,25 @@ export declare function createWorkspaceFilesPort(workspace: WorkspaceFiles, owne
     list(input: {
         path: string;
         limit: number;
-    }): Promise<{
-        path: string;
-        entries: {
+    }, context?: Parameters<FilesPort["list"]>[1]): Promise<{
+        results: {
             path: string;
-            name: string;
             type: "file" | "directory" | "symlink";
-            size: number;
-            modifiedAt: number;
         }[];
-        truncated: boolean;
+        truncated: "limit" | "scan" | null;
+        path: string;
     }>;
     glob(input: {
         path: string;
         pattern: string;
         limit: number;
-    }): Promise<{
+    }, context?: Parameters<FilesPort["glob"]>[1]): Promise<{
+        results: {
+            path: string;
+            type: "file" | "directory";
+        }[];
+        truncated: "limit" | "scan" | null;
         path: string;
-        matches: string[];
-        truncated: boolean;
     }>;
     grep(input: {
         path: string;
@@ -55,14 +93,15 @@ export declare function createWorkspaceFilesPort(workspace: WorkspaceFiles, owne
         regex: boolean;
         ignoreCase: boolean;
         limit: number;
-    }): Promise<{
-        path: string;
-        matches: {
+        include?: string | undefined;
+    }, context?: Parameters<FilesPort["grep"]>[1]): Promise<{
+        results: {
             path: string;
             line: number;
             text: string;
         }[];
-        truncated: boolean;
+        truncated: "limit" | "scan" | null;
+        path: string;
     }>;
     replace(input: Readonly<{
         path: string;
@@ -73,3 +112,14 @@ export declare function createWorkspaceFilesPort(workspace: WorkspaceFiles, owne
         bytes: number;
     }>;
 }>;
+/** Shared REST listing: offsets count visible entries, never ignored candidates. */
+export declare function listWorkspaceFiles(workspace: WorkspaceFiles, input: ComputerFileListInput): Promise<{
+    path: string;
+    entries: {
+        name: string;
+        size: number;
+        modifiedAt: number;
+        type: "file" | "directory" | "symlink";
+    }[];
+    nextOffset: number | null;
+}>;