weir-harness 1.2.3 → 2.0.0

package/src/file-lease/view.js

@@ -0,0 +1,144 @@
+// The read-only ownership view of the status surface (design D13).
+//
+// This module is the ONE place that decides what a user may see about
+// ownership, and it is deliberately the narrowest possible projection:
+//
+//  - three facts and nothing else — who holds which short path, when the hold
+//    started, and how long it can last. No epoch, no generation, no
+//    reservation, no recovery record, no operation history, no fence. Those
+//    concepts were deleted with the durable authority (D12); a view that still
+//    carried them would let the panel grow a story that no longer exists.
+//  - short names only. An absolute path in `path` would leak the user's home
+//    directory into a UI string and, worse, invite someone to "fix" a row by
+//    path. `pathFull` is the separate, mechanically faithful field the
+//    technical layer may use; the panel does not render it by default.
+//  - purity. No IO, no clock, no arbiter, no cordis: `now` arrives as an
+//    argument so the expiry comparison is the caller's clock, exactly the
+//    "read-time comparison" the lease protocol specifies (D2). A lapsed row is
+//    therefore not ownership any more — showing it would invent a state whose
+//    only exit is somebody cleaning it up, which the rebuild forbids.
+//
+// The arbiter's own health is a closed three-value vocabulary (D7): a healthy
+// arbiter arbitrates, a degraded one lost the connection it once had, and an
+// unavailable one was never reached in this process. Anything else is reported
+// as `unavailable` — an unknown state must never be presented as healthy.
+
+import { shortName as shortPathName } from './tools.js'
+
+/** The only shape of this view the panel understands. */
+export const VIEW_SCHEMA_VERSION = 1
+
+/** Closed arbiter vocabulary (design D7); anything else renders as unavailable. */
+export const ARBITER_STATES = Object.freeze(['ok', 'degraded', 'unavailable'])
+
+/** @returns {string | undefined} the value when it is a non-empty string */
+function text(value) {
+  return typeof value === 'string' && value.length > 0 ? value : undefined
+}
+
+/**
+ * A millisecond instant, or `null` when the field is absent. `null` (not 0) is
+ * the view's "no such deadline" — the panel distinguishes "not retained" from
+ * "retained until the epoch".
+ * @param {unknown} value
+ * @returns {number | null}
+ */
+function instant(value) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null
+}
+
+/**
+ * When a lease stops being ownership: `max(expiresAt, holdUntil ?? 0)`, the
+ * protocol's one validity rule (D2). Not a second authority — the arbiter
+ * already applied it; this is what makes the view agree with the arbiter
+ * without asking it again.
+ * @param {any} lease
+ * @returns {number}
+ */
+function validUntil(lease) {
+  const expiresAt = instant(lease?.expiresAt) ?? 0
+  const holdUntil = instant(lease?.holdUntil) ?? 0
+  return Math.max(expiresAt, holdUntil)
+}
+
+/**
+ * The short name of one lease path: relative inside the session's cwd, the
+ * basename outside it. Never absolute (the rule itself lives in `tools.js`, so
+ * the model-facing status text and this view cannot disagree).
+ * @param {string} path
+ * @param {string | undefined} cwd
+ * @returns {string}
+ */
+function shortName(path, cwd) {
+  try {
+    return shortPathName(path, cwd)
+  } catch {
+    // A malformed path must degrade to something renderable, never throw in
+    // the endpoint: the panel is an observability surface, not a validator.
+    return path
+  }
+}
+
+/**
+ * Build the read-only ownership view.
+ *
+ * @param {object} input
+ * @param {any[]} [input.leases] the arbiter's `status` snapshot (`LeaseView[]`)
+ * @param {string | undefined} [input.mineLineage] the calling session's lineage id (design D9)
+ * @param {string | undefined} [input.cwd] the session's working directory (short-name base and scope)
+ * @param {'ok' | 'degraded' | 'unavailable' | string} [input.arbiter] the client's read-only connection state
+ * @param {number} [input.now] read-time instant (epoch ms) used for the expiry comparison
+ * @returns {{
+ *   schemaVersion: number,
+ *   arbiter: 'ok' | 'degraded' | 'unavailable',
+ *   mine: { path: string, pathFull: string, label: string, heldSince: number | null, holdUntil: number | null }[],
+ *   others: { path: string, pathFull: string, holder: { label: string, session: string }, expiresAt: number | null, holdUntil: number | null }[],
+ * }}
+ */
+export function buildLeaseView({ leases, mineLineage, cwd, arbiter, now } = {}) {
+  const at = instant(now) ?? 0
+  const base = text(cwd)
+  const mineId = text(mineLineage)
+  /** @type {any[]} */
+  const mine = []
+  /** @type {any[]} */
+  const others = []
+  for (const lease of Array.isArray(leases) ? leases : []) {
+    if (lease === null || typeof lease !== 'object') continue
+    const path = text(lease.path)
+    if (path === undefined) continue
+    // Lapsed rows are not ownership: ownership ends by itself (D2/D10), and the
+    // view says so instead of presenting a row somebody would have to clear.
+    if (validUntil(lease) <= at) continue
+    const owner = lease.owner !== null && typeof lease.owner === 'object' ? lease.owner : {}
+    const label = text(owner.label) ?? text(owner.session) ?? ''
+    const short = shortName(path, base)
+    const holdUntil = instant(lease.holdUntil)
+    if (mineId !== undefined && text(owner.id) === mineId) {
+      mine.push({ path: short, pathFull: path, label, heldSince: instant(lease.acquiredAt), holdUntil })
+      continue
+    }
+    others.push({
+      path: short,
+      pathFull: path,
+      holder: { label, session: text(owner.session) ?? '' },
+      expiresAt: instant(lease.expiresAt),
+      holdUntil,
+    })
+  }
+  // Deterministic order, independent of the snapshot's own ordering: by the
+  // short name the user actually reads (two basenames may collide), then by the
+  // full path, which is unique per lease and therefore a total order.
+  const byPath = (/** @type {any} */ left, /** @type {any} */ right) => {
+    if (left.path !== right.path) return left.path < right.path ? -1 : 1
+    return left.pathFull < right.pathFull ? -1 : left.pathFull > right.pathFull ? 1 : 0
+  }
+  mine.sort(byPath)
+  others.sort(byPath)
+  return {
+    schemaVersion: VIEW_SCHEMA_VERSION,
+    arbiter: ARBITER_STATES.includes(/** @type {any} */ (arbiter)) ? /** @type {any} */ (arbiter) : 'unavailable',
+    mine,
+    others,
+  }
+}

package/src/hashline-edit/index.js

@@ -4,28 +4,63 @@ import { anchorFor } from './anchors.js'
 import { applyOps, renderMismatch, validateOps } from './apply-ops.js'
 import { diffResult } from './diff.js'
 import { escalationHintMarker, probeEscalation, resolveCallPolicy, sandboxDenialMarker } from './sandbox.js'
+import { createManagedWriteTool, MANAGED_WRITE_NAME } from './write-tool.js'
+import { createEditorLease } from '../file-lease/singleton.js'
+import { isLeaseConflict } from '../file-lease/client.js'
 
 const name = 'weir-hashline-edit'
 const inject = ['tools', 'fs']
 
 export const HASH_EDIT_NAME = 'hash_edit'
 const STOCK_EDIT_NAME = 'edit'
+const STOCK_WRITE_NAME = 'write'
 
 /**
- * Hide the stock edit tool. Uniform mechanism: per-agent restriction on
- * creation. At an agent's scope the stock edit is always *inherited* (from
- * the global layer, or from the preset layer in preset compositions), and
- * inherited tools are restrictable — the agent's catalog hides it. This
- * covers host-level mounts (headless compositions) and preset mounts alike;
- * a mount-time restrict cannot work in either (unscoped at host level; at
- * preset standing scope the fs row's scoped edit is not restrictable).
- * Listeners are awaited before creation resolves, so the restriction lands
- * before the agent's first request.
+ * Install the managed editors on every created agent (design D11): hide the
+ * stock `edit` AND the stock `write`, then provide our own `write` at the SAME
+ * scope.
+ *
+ * Uniform mechanism: per-agent restriction on creation. At an agent's scope the
+ * stock tools are always *inherited* (from the global layer, or from the preset
+ * layer in preset compositions), and inherited tools are restrictable — the
+ * agent's catalog hides them — while a definition registered at that same scope
+ * wins over the denied name. This covers host-level mounts (headless
+ * compositions) and preset mounts alike; a mount-time restrict cannot work in
+ * either (unscoped at host level; at preset standing scope the fs row's scoped
+ * tools are not restrictable). Listeners are awaited before creation resolves,
+ * so the denial and the registration both land before the agent's first
+ * request.
+ *
+ * The two steps must stay in one listener: a deny without the registration
+ * leaves the agent with no writer at all, and a registration without the deny
+ * leaves the unmanaged stock writer reachable. The registration is verified —
+ * if our definition is not the one this agent resolves, it is disposed and the
+ * stock writers stay hidden, because an unmanaged write is exactly what this
+ * path exists to prevent.
+ * @param {any} ctx @param {any} lease @param {() => any} sandboxPolicy
  */
-function hideStockEdit(ctx) {
+function installManagedEditors(ctx, lease, sandboxPolicy) {
+  /** @type {WeakMap<object, any>} definitions this mount installed, per agent */
+  const installed = new WeakMap()
   ctx.on('agent/created', ({ agent }) => {
-    if (!ctx.tools.get(STOCK_EDIT_NAME, agent)) return // this agent has no stock edit
-    agent.ctx.tools.restrict({ deny: [STOCK_EDIT_NAME] })
+    const scope = agent?.ctx?.tools
+    if (typeof scope?.restrict !== 'function') return
+    // Nothing to replace: this agent sees neither stock editor (a composition
+    // without the host fs row). Registering our writer there would only add a
+    // tool whose observation guard could never be answered.
+    if (typeof ctx.tools?.get === 'function'
+      && !ctx.tools.get(STOCK_EDIT_NAME, agent)
+      && !ctx.tools.get(STOCK_WRITE_NAME, agent)) return
+    if (installed.has(agent)) return
+    scope.restrict({ deny: [STOCK_EDIT_NAME, STOCK_WRITE_NAME] })
+    const definition = createManagedWriteTool(ctx, lease, sandboxPolicy())
+    const dispose = typeof scope.register === 'function' ? scope.register(definition) : undefined
+    installed.set(agent, definition)
+    const resolved = typeof ctx.tools?.get === 'function' ? ctx.tools.get(MANAGED_WRITE_NAME, agent) : definition
+    if (resolved === definition) return
+    installed.delete(agent)
+    try { dispose?.() } catch { /* the scope's own teardown may have run first */ }
+    ctx.logger?.warn?.('hashline-edit: the managed write was not installed for this agent; the stock writers stay hidden')
   })
 }
 
@@ -87,11 +122,11 @@ function isSandboxDenial(error) {
 }
 
 function apply(ctx, config = {}) {
-  // Capture once: disposal of managed editing must fail closed, not downgrade.
-  // A sibling row's service becomes visible only after its own apply, so a
-  // deferred provider is accepted too (see the inject after registration).
-  let editLock = ctx.get?.('weirEditLock')
-  let editLockRemoved = false
+  // The injection seam (unit tests, embedders): an explicit client wins and
+  // creates no singleton. Read BEFORE the settings overlay so a settings value
+  // can never shadow it. Default: the process-wide client (D11), resolved on
+  // the first managed write.
+  const leaseClient = config.leaseClient
   // Settings overlay (absent service = no-op): hashlineEdit section wins over row config.
   const settingsOverride = ctx.get?.('weirSettings')?.get('hashlineEdit')
   if (settingsOverride && typeof settingsOverride === 'object') {
@@ -104,6 +139,7 @@ function apply(ctx, config = {}) {
   ctx.inject?.(['sandboxPolicy'], (scope) => {
     sandboxPolicyRef = scope.sandboxPolicy
   })
+  const lease = createEditorLease({ leaseClient, ctx })
 
   // Sandbox escalation capability fact (mirrors the stock fs tools): a
   // confining backend exposes ctx.fs.sandboxMode; only then does hash_edit
@@ -120,9 +156,9 @@ function apply(ctx, config = {}) {
     return { ...downstream, content: rewritten }
   })
 
-  // Optional: hide the stock edit tool from this preset's agents.
+  // Managed editors: hide the stock `edit` and `write`, provide our `write`.
   if (config.hideStockEdit === true) {
-    hideStockEdit(ctx)
+    installManagedEditors(ctx, lease, () => sandboxPolicyRef)
   }
 
   const definition = {
@@ -199,21 +235,31 @@ function apply(ctx, config = {}) {
       }
 
       const after = applyOps(lines, args.edits).join('\n')
-      if (editLockRemoved) throw new Error('hash_edit: the Edit Lock service was removed; refusing an unmanaged write.')
+      // Managed commit (design D2, D11): the lease is acquired for this lineage
+      // BEFORE the write and kept for the remainder of the turn, so a sibling
+      // session is refused with the target untouched. A real conflict is never
+      // rewritten as anything else; an unhealthy arbiter degrades and this edit
+      // proceeds (D7). Anchors, the version guard and the sandbox policy are
+      // unchanged by the wrap.
       let outcome
       try {
-        outcome = editLock ? await editLock.publish(exec, {
-          tool: 'hash_edit', filePath: args.file_path, args, content: after,
-          expected: { kind: 'replaceIfVersion', version: info.version },
-          cwd: resolveCwd, effectivePolicy: policy,
-        }) : await ctx.fs.writeText(
-          target,
-          after,
-          { kind: 'replaceIfVersion', version: info.version },
-          exec.signal,
-          policy,
+        outcome = await lease.client().withLeases(
+          lease.ownerOf(exec.agent),
+          [target.displayPath],
+          lease.scopeOf(exec.agent, resolveCwd),
+          () => ctx.fs.writeText(
+            target,
+            after,
+            { kind: 'replaceIfVersion', version: info.version },
+            exec.signal,
+            policy,
+          ),
         )
       } catch (error) {
+        // A refused claim is the arbiter's answer: pass it through untouched so
+        // the model sees the conflict (and never a stale-version or sandbox
+        // story that did not happen).
+        if (isLeaseConflict(error)) throw error
         if (String(error?.code ?? error?.message ?? '').includes('FS_STALE_VERSION')) {
           throw new Error('hash_edit: the file changed on disk between your read and this edit. Re-read it and copy the current anchors before retrying.')
         }
@@ -235,19 +281,7 @@ function apply(ctx, config = {}) {
       }
     },
   }
-  // Managed mounts claim their exact definition; Edit Lock denies any
-  // unclaimed hash_edit so a mis-ordered composition cannot bypass it.
-  editLock?.claim?.(definition)
   ctx.tools.register(definition)
-  if (!editLock) {
-    ctx.inject?.(['weirEditLock'], (scope) => {
-      if (editLock || editLockRemoved) return
-      editLock = scope.weirEditLock
-      editLock?.claim?.(definition)
-      // Once managed, removal never re-enables direct writes.
-      return () => { editLockRemoved = true }
-    })
-  }
 }
 
 export { name, inject, apply }

package/src/hashline-edit/write-tool.js

@@ -0,0 +1,90 @@
+// The managed `write` tool (design D11), now owned by hashline-edit.
+//
+// Byte-for-byte the tool that used to live in `src/edit-lock/write-tool.js`:
+// same description of the contract, same stock observation guard, same diff
+// metadata, same `fs/observed` event and the same error texts. The single
+// difference is the commit itself — instead of asking a publisher service to
+// write on our behalf, the write happens INSIDE
+// `client.withLeases(owner, [path], scope, () => ctx.fs.writeText(...))`.
+//
+// Why that is not a downgrade: the version guard (`replaceIfVersion` /
+// `createIfAbsent`) still runs in the host filesystem, so no unread overwrite is
+// possible; the lease adds what the version guard cannot give — a sibling
+// session is refused BEFORE any target-side effect, and that claim lasts for the
+// remainder of the turn (design D2). A real conflict refuses the write; an
+// unhealthy arbiter degrades and lets the write through (design D7).
+//
+// Nothing here imports `src/edit-lock/**`, and nothing imports `@deepseek-ai/*`:
+// the filesystem arrives through `ctx`.
+
+import { probeEscalation, resolveCallPolicy } from './sandbox.js'
+import { diffResult } from './diff.js'
+
+/** The stock name this definition replaces at the agent's scope. */
+export const MANAGED_WRITE_NAME = 'write'
+
+/** The observation guards the stock policy may hand back (`fs/write-intent`). */
+const OBSERVATION_GUARDS = ['createIfAbsent', 'replaceIfVersion']
+
+/**
+ * Build the definition only. The caller must hide the inherited stock `write`
+ * at the agent's scope and register THIS definition there, so the managed
+ * writer is the one the agent resolves (fail-closed otherwise).
+ *
+ * @param {any} ctx the row context (`fs`, `waterfall`, `emit`, `emit`-style hooks)
+ * @param {any} lease `{ client(), ownerOf(agent), scopeOf(agent, fallback) }` — see `file-lease/singleton.js`
+ * @param {any} sandboxPolicy the effective-policy provider captured at mount (may be null)
+ * @returns {any} a plain tool definition
+ */
+export function createManagedWriteTool(ctx, lease, sandboxPolicy) {
+  const escalation = probeEscalation(ctx.fs)
+  return {
+    name: MANAGED_WRITE_NAME,
+    description: 'Create or fully replace a UTF-8 text file through the file lease. Read an existing file before overwriting it.',
+    parameters: { type: 'object', properties: {
+      file_path: { type: 'string', description: 'Path to write, resolved by the filesystem backend.' },
+      content: { type: 'string', description: 'Full UTF-8 text content to write.' },
+      ...(escalation?.fields ?? {}),
+    }, required: ['file_path', 'content'] },
+    output: {
+      schema: { type: 'object' },
+      render: (/** @type {any} */ _args, /** @type {any} */ value) => [{ type: 'text', text: `${value.operation === 'create' ? 'Created' : 'Updated'} file: ${value.path}` }],
+      presentationMeta: (/** @type {any} */ _args, /** @type {any} */ value) => ({ diffs: value.fragments }),
+    },
+    async execute(/** @type {any} */ args, /** @type {any} */ exec) {
+      if (typeof args.file_path !== 'string' || !args.file_path.trim() || typeof args.content !== 'string') throw new Error('write requires file_path and content strings')
+      const { policy, resolveCwd } = await resolveCallPolicy(args, {
+        escalation, sandboxPolicy, session: exec.agent?.session, sessionCwd: exec.agent?.session?.header?.cwd,
+        approval: { approver: ctx.get?.('approval'), agent: exec.agent, toolName: MANAGED_WRITE_NAME,
+          ...(exec.callId !== undefined ? {callId: exec.callId} : {}), ...(exec.signal ? {signal: exec.signal} : {}) },
+      })
+      if (!resolveCwd || !policy) throw new Error('managed write requires trusted cwd and effective policy')
+      const target = await ctx.fs.resolve(args.file_path, {cwd: resolveCwd})
+      // Keep the stock observation policy's exact guard; do not stat a fresh
+      // version and thereby silently authorize an unread overwrite.
+      const intent = await ctx.waterfall('fs/write-intent', target, exec, () => undefined)
+      if (!intent || !OBSERVATION_GUARDS.includes(intent.kind)) throw new Error('managed write requires an explicit observation guard')
+      const before = intent.kind === 'replaceIfVersion' ? await ctx.fs.readText(target, exec.signal) : null
+      // The claim is taken before the write and NOT released here: it belongs to
+      // the turn (D2), so a second write of this file in the same turn reuses it.
+      const outcome = await lease.client().withLeases(
+        lease.ownerOf(exec.agent),
+        [target.displayPath],
+        lease.scopeOf(exec.agent, resolveCwd),
+        () => ctx.fs.writeText(target, args.content, intent, exec.signal, policy),
+      )
+      if (!outcome || !('version' in outcome)) throw new Error('write publication not acknowledged')
+      ctx.emit('fs/observed', target, {kind: 'present', version: outcome.version}, exec)
+      const fragments = before === null ? [] : diffResult(target.displayPath, before, args.content).fragments
+      return {
+        path: target.displayPath,
+        // The guard is what decides create-vs-update: `createIfAbsent` can only
+        // have produced a new file, `replaceIfVersion` only replaced one.
+        operation: intent.kind === 'createIfAbsent' ? 'create' : 'update',
+        before,
+        after: args.content,
+        fragments,
+      }
+    },
+  }
+}

package/src/lease-broker/entry.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+// Executable entry for `weir-editlockd`, the edit-lock lease broker.
+//
+// Plain Node: it knows nothing about DSH, cordis or `ctx` — the adapter that
+// talks to it lives in the bundle and speaks the protocol in
+// docs/features/edit-lock-protocol.md.
+//
+// Environment:
+//   WEIR_EDITLOCKD_SOCKET    endpoint address (default: defaultSocketPath())
+//   WEIR_EDITLOCKD_IDLE_MS   idle window before self-exit (default 60000)
+//   WEIR_EDITLOCKD_SWEEP_MS  memory-reclaim period (default 30000)
+//
+// The process ends in exactly two ways: SIGTERM/SIGINT (close, then exit 0), or
+// the idle window elapsing with no connected client (close, then the event loop
+// simply drains). Nothing is written to disk, so both are equally recoverable.
+
+import { readFileSync } from 'node:fs'
+import process from 'node:process'
+import { PROTOCOL } from './protocol.js'
+import { createBroker } from './state.js'
+import { DEFAULT_IDLE_MS, DEFAULT_SWEEP_MS, defaultSocketPath, startServer } from './server.js'
+
+const VERSION_FALLBACK = '0.0.0'
+
+/**
+ * Version reported by the handshake, read from this package's manifest.
+ * @returns {string}
+ */
+function readDaemonVersion() {
+  try {
+    const manifest = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'))
+    return typeof manifest.version === 'string' && manifest.version.length > 0 ? manifest.version : VERSION_FALLBACK
+  } catch {
+    // A missing manifest must not stop the daemon: the version is diagnostic.
+    return VERSION_FALLBACK
+  }
+}
+
+/**
+ * Read an interval override; anything that is not a positive integer falls back
+ * to the default so a typo cannot turn the daemon into a busy loop or a
+ * permanent resident.
+ * @param {string} name
+ * @param {number} fallback
+ * @returns {number}
+ */
+function readInterval(name, fallback) {
+  const raw = process.env[name]
+  if (raw === undefined) return fallback
+  const value = Number.parseInt(raw, 10)
+  return Number.isFinite(value) && value > 0 ? value : fallback
+}
+
+const daemonVersion = readDaemonVersion()
+const socketPath = process.env.WEIR_EDITLOCKD_SOCKET || defaultSocketPath()
+const idleMs = readInterval('WEIR_EDITLOCKD_IDLE_MS', DEFAULT_IDLE_MS)
+const sweepMs = readInterval('WEIR_EDITLOCKD_SWEEP_MS', DEFAULT_SWEEP_MS)
+
+/** @type {Awaited<ReturnType<typeof startServer>> | null} */
+let server = null
+
+// The kernel hands events to the transport by connection id; the sink reads the
+// late-bound server handle because the broker must exist before startServer can
+// register connections on it.
+const broker = createBroker({
+  onEvent: (connectionId, event) => {
+    if (server !== null) server.send(connectionId, event)
+  },
+})
+
+try {
+  server = await startServer({ socketPath, broker, protocol: PROTOCOL, daemonVersion, idleMs, sweepMs })
+} catch (error) {
+  const detail = error instanceof Error ? error.message : String(error)
+  process.stderr.write(`weir-editlockd: ${detail}\n`)
+  process.exit(1)
+}
+
+process.stderr.write(`weir-editlockd ${daemonVersion} listening on ${socketPath}\n`)
+
+let shuttingDown = false
+
+async function shutdown() {
+  if (shuttingDown) return
+  shuttingDown = true
+  const handle = server
+  if (handle !== null) {
+    try {
+      await handle.close()
+    } catch {
+      // Shutting down regardless: there is no state to preserve.
+    }
+  }
+  process.exit(0)
+}
+
+process.on('SIGTERM', shutdown)
+process.on('SIGINT', shutdown)

package/src/lease-broker/node-contracts.d.ts

@@ -0,0 +1,63 @@
+// Node transport contracts consumed by the lease-broker daemon, declared next
+// to the code that uses them.
+//
+// `checkJs` runs with `types: []` (no @types/node), so the Node surface this
+// package compiles against is declared in types/platform.d.ts. That file covers
+// the modules the rest of the bundle consumes; the daemon is the only consumer
+// of `node:net`, `node:os`, the global `process`, and `unlinkSync`, and its
+// subtree is a self-contained pure-Node module (no DSH, no cordis), so its
+// daemon-only contracts stay here. Ambient declarations merge with the shared
+// ones, which is why the added `unlinkSync` below extends `node:fs` instead of
+// redeclaring it.
+
+declare module 'node:net' {
+  interface SocketError extends Error {
+    code?: string;
+  }
+  export interface Socket {
+    destroyed: boolean;
+    setEncoding(encoding: string): void;
+    setNoDelay(noDelay?: boolean): void;
+    write(chunk: string): boolean;
+    end(data?: string): void;
+    destroy(error?: Error): void;
+    on(event: 'data', listener: (chunk: string) => void): Socket;
+    on(event: 'close' | 'end', listener: () => void): Socket;
+    on(event: 'error', listener: (error: SocketError) => void): Socket;
+    once(event: 'connect', listener: () => void): Socket;
+    once(event: 'error', listener: (error: SocketError) => void): Socket;
+  }
+  export interface Server {
+    listen(options: { path: string }, callback?: () => void): Server;
+    close(callback?: () => void): Server;
+    on(event: 'connection', listener: (socket: Socket) => void): Server;
+    on(event: 'error' | 'close', listener: (error?: SocketError) => void): Server;
+  }
+  export function createServer(options: { allowHalfOpen?: boolean }, connectionListener?: (socket: Socket) => void): Server;
+  export function createConnection(options: { path: string }): Socket;
+}
+
+declare module 'node:os' {
+  export function tmpdir(): string;
+  export function homedir(): string;
+}
+
+declare module 'node:fs' {
+  export function unlinkSync(path: string): void;
+}
+
+// The global `process` that arrives with the compiler's own libs is not the
+// Node one (no `exit`/`on`/`stderr`/`getuid`), so the daemon imports the module
+// explicitly instead of relying on the global.
+declare module 'node:process' {
+  const process: {
+    platform: string;
+    pid: number;
+    env: Record<string, string | undefined>;
+    getuid?: () => number;
+    exit(code?: number): never;
+    on(event: string, listener: (...args: any[]) => void): void;
+    stderr: { write(chunk: string): boolean };
+  };
+  export default process;
+}