@ricsam/r5d-worker 0.0.182 → 0.0.184

package/dist/cjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5d-worker",
-  "version": "0.0.182",
+  "version": "0.0.184",
   "type": "commonjs"
 }

package/dist/mjs/internal-r5dctl.cjs

@@ -20605,7 +20605,7 @@ function resolveEntrypointPath(entrypoint) {
   }
 }
 function getR5dctlVersion() {
-  if (true) return "0.0.182";
+  if (true) return "0.0.184";
   const entrypoint = process.argv[1] ? resolveEntrypointPath(process.argv[1]) : null;
   let current = entrypoint ? import_node_path2.default.dirname(entrypoint) : process.cwd();
   for (let index = 0; index < 12; index += 1) {

package/dist/mjs/main.mjs

@@ -7,7 +7,7 @@ import { startManagerRpc } from "./runtime/releases/rpc-main.mjs";
 import { ManagerRpcConfig } from "./runtime/releases/rpc-protocol.mjs";
 const args = process.argv.slice(2);
 if (args.includes("--version")) {
-  console.log(`r5d-worker ${true ? "0.0.182" : "development"}`);
+  console.log(`r5d-worker ${true ? "0.0.184" : "development"}`);
 } else if (!args.length || args.includes("--help")) {
   console.log(
     "Usage: r5d-worker start --label <label> [--root <dir>] [--base-url <url>] [--token <worker-token>] [--initial-sync merge|reset]\n       r5d-worker executor /absolute/private/config.json\n       r5d-worker manager /absolute/private/config.json\n\nRun independently supervised durable runtime services. Provision configuration with r5dinfra."
@@ -15,7 +15,7 @@ if (args.includes("--version")) {
 } else if (args[0] === "start") {
   const runtime = await startPersonalWorker(
     parsePersonalWorkerOptions(args.slice(1)),
-    true ? "0.0.182" : "development"
+    true ? "0.0.184" : "development"
   );
   console.log(`Worker connected: ${runtime.resourceId}`);
   let closing = false;

package/dist/mjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5d-worker",
-  "version": "0.0.182",
+  "version": "0.0.184",
   "type": "module"
 }

package/dist/mjs/personal/client.mjs

@@ -66,6 +66,28 @@ function parsePersonalWorkerOptions(args, environment = process.env) {
     initialSync
   };
 }
+function transportFailure(error) {
+  const name = error instanceof Error ? error.name : "";
+  return new PersonalResponseError(name === "TimeoutError" || name === "AbortError" ? "personal_transport_timeout" : "personal_transport_failed", 0, false);
+}
+async function readPersonalResponse(response) {
+  let data;
+  try {
+    data = await response.json();
+  } catch {
+    throw new PersonalResponseError(response.ok ? "personal_transport_invalid" : "personal_transport_rejected", response.status, false);
+  }
+  const body = data && typeof data === "object" && !Array.isArray(data) ? data : null;
+  if (!response.ok) {
+    throw new PersonalResponseError(
+      typeof body?.error === "string" ? body.error : "personal_transport_rejected",
+      response.status,
+      body?.rejectedBeforeAdmission === true
+    );
+  }
+  if (!body) throw new PersonalResponseError("personal_transport_invalid", response.status, false);
+  return body;
+}
 function safeError(error) {
   const value = error.code;
   return typeof value === "string" && /^[a-zA-Z0-9_-]{1,100}$/.test(value) ? value : "personal_operation_unknown";
@@ -93,18 +115,19 @@ async function startPersonalWorker(options, version) {
   }
   const endpoint = `/api/personal/resources/worker/${encodeURIComponent(identity.resourceId)}`;
   async function request(pathname, body, timeoutMs = 3e4) {
-    const response = await fetch(options.baseUrl + pathname, {
-      method: "POST",
-      headers: { authorization: `Bearer ${options.credential}`, "content-type": "application/json" },
-      redirect: "error",
-      body: JSON.stringify(body),
-      signal: AbortSignal.timeout(timeoutMs)
-    });
-    const data = await response.json();
-    if (!response.ok) {
-      throw new PersonalResponseError(typeof data.error === "string" ? data.error : "personal_transport_rejected", response.status, data.rejectedBeforeAdmission === true);
+    let response;
+    try {
+      response = await fetch(options.baseUrl + pathname, {
+        method: "POST",
+        headers: { authorization: `Bearer ${options.credential}`, "content-type": "application/json" },
+        redirect: "error",
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(timeoutMs)
+      });
+    } catch (error) {
+      throw transportFailure(error);
     }
-    return data;
+    return readPersonalResponse(response);
   }
   const cli = await resolvePersonalCliEntrypoint(options.cliEntrypoint, version);
   let bootId = randomUUID();
@@ -134,14 +157,18 @@ async function startPersonalWorker(options, version) {
         if (!response || !("result" in response)) throw new Error("Invalid scoped storage response");
         return response.result;
       } catch (error) {
-        if (error instanceof PersonalResponseError && storageErrorCodes.has(error.code))
-          throw new WorkspaceError(error.code, "Scoped storage rejected the request; retain its original operation identity", error.rejectedBeforeAdmission);
+        if (error instanceof PersonalResponseError)
+          throw new WorkspaceError(
+            error.code,
+            "Scoped storage rejected the request; retain its original operation identity",
+            error.rejectedBeforeAdmission && storageErrorCodes.has(error.code)
+          );
         throw error;
       }
     },
     publicationReport: async (report) => {
       const response = await request(`${endpoint}/publication`, { instanceId: identity.instanceId, report });
-      const result = response?.result;
+      const result = response.result;
       return result && typeof result === "object" && typeof result.incidentId === "string" ? { incidentId: result.incidentId } : void 0;
     }
   });
@@ -269,6 +296,9 @@ async function startPersonalWorker(options, version) {
   };
 }
 export {
+  PersonalResponseError,
   parsePersonalWorkerOptions,
-  startPersonalWorker
+  readPersonalResponse,
+  startPersonalWorker,
+  transportFailure
 };

package/dist/mjs/personal/publication-refusal.mjs

@@ -1,3 +1,4 @@
+import { WorkspaceError } from "../runtime/workspace/contracts.mjs";
 const CONFLICT_PUBLICATION_CODES = /* @__PURE__ */ new Set([
   "conflict",
   "sync_conflict",
@@ -9,8 +10,20 @@ const TRANSIENT_PUBLICATION_CODES = /* @__PURE__ */ new Set([
   "apply_refused",
   "mirror_advanced",
   "authority_closed",
-  "busy"
+  "busy",
+  // The relay or the storage behind it did not answer this cycle: nothing was
+  // refused about the workspace, the next cycle asks again.
+  "internal_error",
+  "personal_transport_failed",
+  "personal_transport_timeout",
+  "personal_transport_rejected",
+  "personal_transport_invalid"
 ]);
+function publicationFailureDetail(error) {
+  if (error instanceof WorkspaceError) return { code: error.code };
+  const detail = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+  return { code: "publication_failed", detail: detail.replace(/\s+/g, " ").slice(0, 300) };
+}
 const BLOCKED_PUBLICATION_CODES = /* @__PURE__ */ new Set([
   "secret_or_runtime_path",
   "secret_content",
@@ -42,6 +55,7 @@ export {
   PUBLICATION_OBSERVATION_THRESHOLDS,
   STUCK_OPERATION_OBSERVATIONS,
   TRANSIENT_PUBLICATION_CODES,
+  publicationFailureDetail,
   publicationRefusalElects,
   publicationRefusalOutcome
 };

package/dist/mjs/personal/runtime.mjs

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { publicationRefusalElects, publicationRefusalOutcome, TRANSIENT_PUBLICATION_CODES } from "./publication-refusal.mjs";
+import { publicationFailureDetail, publicationRefusalElects, publicationRefusalOutcome, TRANSIENT_PUBLICATION_CODES } from "./publication-refusal.mjs";
 import { PersonalTcpManager } from "./tcp.mjs";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { promises as fs } from "node:fs";
@@ -273,8 +273,8 @@ exec ${quote(executable)} ${quote(cli)} "$@"
           failedPublicationAttempts.delete("workspace");
           results.push({ workbenchId: "workspace", ...outer });
         } catch (error) {
-          const code = error instanceof WorkspaceError ? error.code : "publication_failed";
-          results.push({ workbenchId: "workspace", error: code });
+          const { code, detail } = publicationFailureDetail(error);
+          results.push({ workbenchId: "workspace", error: code, ...detail ? { detail } : {} });
           if (!TRANSIENT_PUBLICATION_CODES.has(code) && options.publicationReport) {
             let startingHead = null;
             try {
@@ -332,12 +332,13 @@ exec ${quote(executable)} ${quote(cli)} "$@"
         (results) => {
           const deferred = results.filter((result) => result.error && result.error !== "remediation_paused" && !TRANSIENT_PUBLICATION_CODES.has(result.error));
           if (deferred.length)
-            process.stderr.write(`[r5d-worker] periodic workspace publication deferred: ${deferred.map((result) => `${result.workbenchId}:${result.error}`).join(", ")}
+            process.stderr.write(`[r5d-worker] periodic workspace publication deferred: ${deferred.map((result) => `${result.workbenchId}:${result.error}${result.detail ? ` (${result.detail})` : ""}`).join(", ")}
 `);
           if (publication === next) publication = null;
         },
         (error) => {
-          process.stderr.write(`[r5d-worker] periodic workspace publication failed: ${error instanceof WorkspaceError ? error.code : "publication_failed"}
+          const failure = publicationFailureDetail(error);
+          process.stderr.write(`[r5d-worker] periodic workspace publication failed: ${failure.code}${failure.detail ? ` (${failure.detail})` : ""}
 `);
           if (publication === next) publication = null;
         }
@@ -375,7 +376,14 @@ exec ${quote(executable)} ${quote(cli)} "$@"
         if (command.method === "search") return authority.searchFiles(identity, WorkspaceSearch.parse(command));
       }
       if (request.kind === "terminal") {
-        if (command.method === "open" || command.method === "start") await authority.ensureHydrated(identity);
+        if (command.method === "open" || command.method === "start") {
+          try {
+            await authority.ensureHydrated(identity);
+          } catch (error) {
+            const code = error instanceof WorkspaceError ? error.code : "hydration_failed";
+            throw new WorkspaceError(code, `Shell not opened: checkout hydration failed (${code})`, true);
+          }
+        }
         if (command.method === "open" || command.method === "start") {
           const argv = command.method === "open" ? ["/bin/bash", "--noprofile", "--norc", ...command.command ? ["-c", command.command] : []] : ["/bin/sh", "-c", command.command];
           return {

package/dist/mjs/runtime/workspace/authority.mjs

@@ -1242,9 +1242,44 @@ class WorkspaceAuthority {
       b.state.mirroredHead = null;
       await this.save(b);
       const result = this.outerEnabled(b) ? await this.hydrateLinkedIdle(b, identity) : await this.hydrateIdle(b, identity);
+      if (this.outerEnabled(b)) await this.restoreOuterEntries(b);
       return { ...result, reset: true, retained: true };
     }));
   }
+  /** A checkout rebuilt from its branch head is not what the workspace holds
+   * for it: the branch does not track the files every worker synchronizes (an
+   * install's lock file, a note, a sentinel), it has not committed the edits
+   * they published, and it still carries what they deleted. The checkout is
+   * brought to what a worker installing it afresh receives, the outer head's
+   * subtree over the branch head, so the next cycle sees the canonical state
+   * again instead of publishing the difference to every other worker (stage
+   * 2026-09-17 run 25 published the sentinels' absence as deletions). The
+   * discarded divergence is already retained beside the checkout's state. */
+  async restoreOuterEntries(b) {
+    const workTree = this.config.workspaceRoot;
+    if (!workTree) return;
+    const { repo, state } = await this.outer(b.config.userId);
+    if (!state.head) return;
+    const relative = path.relative(workTree, b.config.cwd);
+    if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) return;
+    const root = relative.split(path.sep).join("/");
+    const held = (await repo.listTree(await repo.treeOf(state.head))).filter((entry) => entry.mode !== "160000" && entry.file.startsWith(`${root}/`));
+    if (!held.length) return;
+    await repo.restore(state.head, held.map((entry) => entry.file));
+    const entries = new Set(held.map((entry) => entry.file));
+    const missing = [...await this.innerTracked(b)].map((file) => `${root}/${file}`).filter((file) => !entries.has(file));
+    if (!missing.length) return;
+    const excluded = await repo.ignored(missing);
+    for (const file of missing) {
+      if (excluded.has(file)) continue;
+      const absolute = path.join(workTree, file);
+      const stat = await fs.lstat(absolute).catch((error) => {
+        if (error.code === "ENOENT" || error.code === "ENOTDIR") return null;
+        throw error;
+      });
+      if (stat?.isFile()) await fs.rm(absolute);
+    }
+  }
   // ---- Outer repository ---------------------------------------------------
   outerEnabled(b) {
     return !!this.options.accountStorage && (!b || b.config.rootProfile === "account" || this.linkedWorkbench(b));
@@ -1896,7 +1931,11 @@ class WorkspaceAuthority {
   }
   async runRoute(identity, run) {
     const b = await this.bench(identity);
-    if (run.userId !== identity.userId || run.sessionId !== identity.sessionId || !b.state.runs[run.operationId] || (b.state.runs[run.operationId].sessionId ?? b.config.sessionId) !== identity.sessionId)
+    if (run.userId !== identity.userId || run.sessionId !== identity.sessionId)
+      throw new WorkspaceError("forbidden", "Run does not belong to this workbench", true);
+    if (!b.state.runs[run.operationId])
+      throw new WorkspaceError("run_not_found", "No run with this operation id was admitted into this workbench", true);
+    if ((b.state.runs[run.operationId].sessionId ?? b.config.sessionId) !== identity.sessionId)
       throw new WorkspaceError("forbidden", "Run does not belong to this workbench", true);
     if (b.state.runs[run.operationId].state === "rejected_capacity")
       throw new WorkspaceError("run_not_admitted", "This operation was definitively rejected; no executor run exists", true);

package/dist/mjs/runtime/workspace/outer.mjs

@@ -218,9 +218,7 @@ class OuterRepository {
     }
     const paths = [...untracked.values()].flat();
     if (!paths.length) return;
-    const { code, stdout } = await this.result(["check-ignore", "--no-index", "-z", "--stdin"], `${paths.join("\0")}\0`);
-    if (code !== 0 && code !== 1) throw new WorkspaceError("git_failed", "Outer repository ignore rules are unreadable");
-    const ignored = new Set(nulSplit(stdout));
+    const ignored = await this.ignored(paths);
     const removals = [];
     for (const [root, files] of untracked) {
       const drop = files.filter((file) => ignored.has(file));
@@ -229,6 +227,14 @@ class OuterRepository {
     }
     if (removals.length) await this.run(["update-index", "--force-remove", "-z", "--stdin"], `${removals.join("\0")}\0`);
   }
+  /** The subset of `paths` the workspace's ignore rules exclude. --no-index
+   * evaluates the nested ignore files for tracked paths as well. */
+  async ignored(paths) {
+    if (!paths.length) return /* @__PURE__ */ new Set();
+    const { code, stdout } = await this.result(["check-ignore", "--no-index", "-z", "--stdin"], `${paths.join("\0")}\0`);
+    if (code !== 0 && code !== 1) throw new WorkspaceError("git_failed", "Outer repository ignore rules are unreadable");
+    return new Set(nulSplit(stdout));
+  }
   /** Staging records a symlink as a link entry, and a nested repository that
    * appeared between the walk and the add as a gitlink. Neither can be
    * materialized on another host; both are dropped from the index without
@@ -271,6 +277,13 @@ class OuterRepository {
     await this.run(["read-tree", GitOid.parse(commit)]);
     await this.run(["checkout-index", "-a"]);
   }
+  /** Materialize `paths` of `commit` into the index and the working tree,
+   * leaving every other path alone. */
+  async restore(commit, paths) {
+    if (!paths.length) return;
+    for (const file of paths) safeTreePath(file);
+    await this.run(["checkout", GitOid.parse(commit), "--pathspec-from-file=-", "--pathspec-file-nul", "--"], `${paths.join("\0")}\0`);
+  }
   /** Reset index and working tree to a commit, deleting tracked paths it lacks.
    * Never `clean`: the second `-f` that would reach nested repositories is the
    * one switch this repository must never pass. */

package/dist/types/personal/client.d.ts

@@ -1,3 +1,9 @@
+export declare class PersonalResponseError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly rejectedBeforeAdmission: boolean;
+    constructor(code: string, status: number, rejectedBeforeAdmission: boolean);
+}
 /** What the first synchronization after `r5d-worker start` does to checkouts
  * that diverged from the server while the worker was away: `merge` integrates
  * them and opens a conflict remediation when needed (the default); `reset`
@@ -14,6 +20,20 @@ export type PersonalWorkerOptions = {
     pollTimeoutMs?: number;
 };
 export declare function parsePersonalWorkerOptions(args: string[], environment?: Record<string, string | undefined>): PersonalWorkerOptions;
+/** A request that never got an answer is a typed, transient transport
+ * failure: a timed-out or refused connection is not the platform refusing
+ * anything, and the journal names it rather than the bare `publication_failed`
+ * it became (stage 2026-09-17 run 25). */
+export declare function transportFailure(error: unknown): PersonalResponseError;
+/** Every relay answer is a JSON object: a refusal names its `error` code and
+ * whether it was rejected before admission, a success carries the route's own
+ * fields. The caller names the fields it reads. */
+export type PersonalResponseBody = {
+    [field: string]: unknown;
+};
+/** The relay answers JSON; anything else (an edge's error page, an empty body)
+ * is a typed transport rejection carrying the status, never a parse error. */
+export declare function readPersonalResponse<T extends PersonalResponseBody = PersonalResponseBody>(response: Response): Promise<T>;
 /** HTTP reconnects never replace the local source/PTY keeper. */
 export declare function startPersonalWorker(options: PersonalWorkerOptions, version: string): Promise<{
     resourceId: string;

package/dist/types/personal/publication-refusal.d.ts

@@ -11,6 +11,13 @@ export declare const CONFLICT_PUBLICATION_CODES: ReadonlySet<string>;
  * landing, or the mirror moved between read and publish. The next cycle
  * repeats the work; nothing durable happened and nothing is reported. */
 export declare const TRANSIENT_PUBLICATION_CODES: ReadonlySet<string>;
+/** The journal's account of a synchronization failure: a typed refusal is its
+ * code; anything else keeps its name and message, since the code alone
+ * (`publication_failed`) told nobody what broke (stage 2026-09-17 run 25). */
+export declare function publicationFailureDetail(error: unknown): {
+    code: string;
+    detail?: string;
+};
 /** Refused because the source candidate itself is unsafe or oversized. */
 export declare const BLOCKED_PUBLICATION_CODES: ReadonlySet<string>;
 /** Consecutive identical observations required before electing an incident.

package/dist/types/personal/runtime.d.ts

@@ -163,6 +163,7 @@ export declare function openPersonalWorkerRuntime(options: {
         head?: string | null;
         unchanged?: boolean;
         error?: string;
+        detail?: string;
     }[]>;
     subscribeTerminal: (input: {
         sessionId: string;

package/dist/types/runtime/workspace/authority.d.ts

@@ -383,6 +383,16 @@ export declare class WorkspaceAuthority {
         retained: boolean;
         head: string;
     }>;
+    /** A checkout rebuilt from its branch head is not what the workspace holds
+     * for it: the branch does not track the files every worker synchronizes (an
+     * install's lock file, a note, a sentinel), it has not committed the edits
+     * they published, and it still carries what they deleted. The checkout is
+     * brought to what a worker installing it afresh receives, the outer head's
+     * subtree over the branch head, so the next cycle sees the canonical state
+     * again instead of publishing the difference to every other worker (stage
+     * 2026-09-17 run 25 published the sentinels' absence as deletions). The
+     * discarded divergence is already retained beside the checkout's state. */
+    private restoreOuterEntries;
     private outerEnabled;
     private outerStateFile;
     private outer;

package/dist/types/runtime/workspace/outer.d.ts

@@ -93,6 +93,9 @@ export declare class OuterRepository {
      * published. The seeding invariant holds: a checkout never loses its last
      * outer entry. */
     private evictIgnored;
+    /** The subset of `paths` the workspace's ignore rules exclude. --no-index
+     * evaluates the nested ignore files for tracked paths as well. */
+    ignored(paths: readonly string[]): Promise<ReadonlySet<string>>;
     /** Staging records a symlink as a link entry, and a nested repository that
      * appeared between the walk and the add as a gitlink. Neither can be
      * materialized on another host; both are dropped from the index without
@@ -109,6 +112,9 @@ export declare class OuterRepository {
     apply(fromTree: string, toTree: string): Promise<void>;
     /** Materialize a commit into a working tree that holds none of its paths yet. */
     checkout(commit: string): Promise<void>;
+    /** Materialize `paths` of `commit` into the index and the working tree,
+     * leaving every other path alone. */
+    restore(commit: string, paths: readonly string[]): Promise<void>;
     /** Reset index and working tree to a commit, deleting tracked paths it lacks.
      * Never `clean`: the second `-f` that would reach nested repositories is the
      * one switch this repository must never pass. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ricsam/r5d-worker",
-  "version": "0.0.182",
+  "version": "0.0.184",
   "type": "module",
   "main": "./dist/mjs/main.mjs",
   "module": "./dist/mjs/main.mjs",
@@ -21,7 +21,7 @@
     "r5d-worker": "dist/mjs/main.mjs"
   },
   "dependencies": {
-    "@ricsam/r5d-api": "^0.0.182",
+    "@ricsam/r5d-api": "^0.0.184",
     "node-pty": "1.1.0",
     "zod": "^4.1.13",
     "picomatch": "^4.0.3"