tardie 0.1.0 → 0.2.0-rc.1

package/README.md

@@ -29,27 +29,46 @@ $$\lbrace\mathrm{transitions}\rbrace = f(\mathrm{log})$$
 
 ## Quickstart
 
-Install Tardigrade and run the default agent. Use Bun 1.4 or later.
+### For agents
+
+Copy this prompt into your coding agent, or install the [Tardigrade skill](skills/tardigrade/SKILL.md):
+
+```text
+Use https://github.com/clavia-labs/tardigrade and follow skills/tardigrade/SKILL.md to create, author, build, push, and run a local actor. Share its Voyager trace URL.
+```
+
+### For developers
+
+Install Tardigrade and initialize an editable template actor. Use Bun 1.4 or later.
 
 ```bash
 bun add -g tardie
+tdg init researcher
+cd researcher
+```
+
+The `init` command creates `researcher/actor.ts` from the bundled template. Read the [Quickstart guide](docs/quickstart.md) to understand the framework, then edit `actor.ts` to describe the agent. Build and push the result into the local actor registry:
+
+```bash
+tdg build actor.ts
+tdg push actor.ts --target local
 tdg dev
 ```
 
-Start a thread from another shell:
+Keep `tdg dev` running. Start the actor from another shell in the same directory:
 
 ```bash
-tdg run "read this repo and tell me what it does"
+tdg run "read this repo and tell me what it does" --actor researcher
 ```
 
-Watch the live trajectory at [localhost:4242](http://localhost:4242).
+Voyager opens at [localhost:4242](http://localhost:4242) by default. `tdg run` prints the direct Voyager URL for the new trace.
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="docs/assets/voyager-dark.png">
   <img alt="The voyager: a thread's log, one row per event" src="docs/assets/voyager-light.png">
 </picture>
 
-## Build one
+## Build your own harness
 
 ```bash
 bun add tardie

package/examples/quickstart/actor.ts

@@ -0,0 +1,49 @@
+import {
+  agentOf,
+  agentsPackage,
+  budget,
+  codeModeFor,
+  compaction,
+  defineActor,
+  fetchPackage,
+  filesPackage,
+  reply,
+  workspacePackage
+} from "tardie"
+
+// actorName is the stable name used by build, push, and run.
+const actorName = "researcher"
+
+// actorInstructions is the main place to describe the job and its expected answer.
+const actorInstructions = `
+You are ${actorName}, a focused research agent.
+
+Investigate the user's request carefully.
+Use project files as evidence.
+Delegate independent research when it helps.
+Return a concise answer with concrete findings.
+`.trim()
+
+const instructions = {
+  name: "instructions",
+  system: actorInstructions
+}
+
+export default defineActor({
+  name: actorName,
+  // agentOf combines small capabilities into the actor's behavior.
+  actor: agentOf([
+    instructions,
+    // codeModeFor gives the model one code tool over the packages listed here.
+    codeModeFor({
+      // packages grant access to local files, HTTP, child agents, and saved tool results.
+      packages: [filesPackage(), fetchPackage(), agentsPackage(), workspacePackage()]
+    }),
+    // reply returns a finished turn to the actor that delegated it.
+    reply,
+    // budget stops work tools when the turn reaches its tool-call limit.
+    budget,
+    // compaction summarizes older context when a long turn outgrows its context window.
+    compaction
+  ])
+})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tardie",
-  "version": "0.1.0",
+  "version": "0.2.0-rc.1",
   "license": "MIT",
   "author": "Clavia, Inc.",
   "description": "A durable agent harness. State is a pure function of the log.",
@@ -17,7 +17,8 @@
   },
   "files": [
     "src",
-    "ui"
+    "ui",
+    "examples"
   ],
   "engines": {
     "bun": ">=1.4.0"

package/src/cli/build.ts

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto"
 import { mkdtemp, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises"
 import { dirname, join, resolve } from "node:path"
-import { pathToFileURL } from "node:url"
+import { fileURLToPath, pathToFileURL } from "node:url"
 
 import {
   ACTOR_ARTIFACT_VERSION,
@@ -10,9 +10,12 @@ import {
   type ActorDefinition
 } from "tardie"
 
+import { shellWord } from "./workflow"
+
 export const DEFAULT_BUILD_DIRECTORY = ".tardigrade/build"
 export const ACTOR_MODULE_FILE = "actor.mjs"
 export const ACTOR_MANIFEST_FILE = "manifest.json"
+export const TARDIE_ENTRY = fileURLToPath(import.meta.resolve("tardie"))
 
 export interface BuildActorOptions {
   readonly out?: string
@@ -45,6 +48,13 @@ const definitionOf = async (modulePath: string): Promise<ActorDefinition<unknown
   return candidate as ActorDefinition<unknown>
 }
 
+export const tardiePlugin = (entry: string = TARDIE_ENTRY): Bun.BunPlugin => ({
+  name: "tardie",
+  setup(builder) {
+    builder.onResolve({ filter: /^tardie$/ }, () => ({ path: entry }))
+  }
+})
+
 export const buildActor = async (entry: string, options: BuildActorOptions = {}): Promise<BuiltActor> => {
   const cwd = resolve(options.cwd ?? process.cwd())
   const source = resolve(cwd, entry)
@@ -59,7 +69,8 @@ export const buildActor = async (entry: string, options: BuildActorOptions = {})
       target: "bun",
       format: "esm",
       minify: false,
-      sourcemap: "none"
+      sourcemap: "none",
+      plugins: [tardiePlugin()]
     })
     if (!result.success) {
       const detail = result.logs.map((log) => log.message).join("\n")
@@ -99,9 +110,12 @@ export const buildActor = async (entry: string, options: BuildActorOptions = {})
   }
 }
 
-export const buildSummary = (built: BuiltActor): string =>
+export const buildSummary = (built: BuiltActor, entry: string): string =>
   [
     `built ${built.manifest.name}`,
     `at    ${built.directory}`,
-    `hash  ${built.manifest.digest}`
+    `hash  ${built.manifest.digest}`,
+    "",
+    "next",
+    `  tdg push ${shellWord(entry)} --target local`
   ].join("\n")

package/src/cli/commands.ts

@@ -6,11 +6,13 @@ import { modelIsConfigured } from "tardie/server/host"
 
 import { buildActor, buildSummary, DEFAULT_BUILD_DIRECTORY } from "./build"
 import { readFileConfig, resolveRemote, resolveServer } from "./config"
-import { availableDevPort, DEFAULT_MIN_PORT, DEV_URL_HOST, dev, openBrowser } from "./dev"
+import { availableDevPort, DEFAULT_ACTOR_REFRESH_MILLIS, DEFAULT_MIN_PORT, DEV_URL_HOST, dev, openBrowser } from "./dev"
+import { initActor, initSummary } from "./init"
 import { DEFAULT_ACTOR_DIRECTORY, pushActor, pushSummary, PUSH_TARGETS } from "./push"
 import { homeOf, HOME_MISSING, setupJson, setupPrompt, setupSummary, writeSetup } from "./setup"
 import { actorsTable, threadsTable, DEFAULT_DETAIL_WIDTH, eventsTable, jsonOf, turnLines } from "./render"
 import { Cli, type CliProjections } from "./services"
+import { traceUrlFor } from "./workflow"
 
 // The command tree. Every command is a declaration: its flags, its arguments, and its description
 // are values, so the help a person reads and the completions a shell installs are generated from
@@ -159,6 +161,36 @@ export const setupCommand = Command.make("setup", { json }, (flags) =>
     ])
   )
 
+export const initCommand = Command.make("init", {
+  name: Argument.string("name").pipe(Argument.withDescription("The actor name")),
+  dir: Flag.string("dir").pipe(
+    Flag.withDescription("The directory to create. Defaults to a directory named after the actor."),
+    Flag.optional
+  ),
+  force: Flag.boolean("force").pipe(
+    Flag.withDescription("Replace actor.ts when it already exists."),
+    Flag.withDefault(false)
+  ),
+  json
+}, (flags) =>
+  Effect.gen(function*() {
+    const directory = stated(flags.dir)
+    const initialized = yield* Effect.tryPromise({
+      try: () => initActor(flags.name, {
+        ...(directory === undefined ? {} : { directory }),
+        force: flags.force
+      }),
+      catch: userErrorOf
+    })
+    yield* Console.log(flags.json ? jsonOf(initialized) : initSummary(initialized))
+  })).pipe(
+    Command.withDescription("Create an editable actor from the bundled quickstart."),
+    Command.withExamples([
+      { command: "tdg init researcher", description: "Create researcher/actor.ts and print the local workflow" },
+      { command: "tdg init reviewer --dir actors/reviewer", description: "Create the actor in a stated directory" }
+    ])
+  )
+
 export const buildCommand = Command.make("build", {
   entry: Argument.string("entry").pipe(Argument.withDescription("The actor source file to bundle")),
   out: Flag.string("out").pipe(
@@ -173,7 +205,7 @@ export const buildCommand = Command.make("build", {
       try: () => buildActor(flags.entry, out === undefined ? {} : { out }),
       catch: userErrorOf
     })
-    yield* Console.log(flags.json ? jsonOf(built) : buildSummary(built))
+    yield* Console.log(flags.json ? jsonOf(built) : buildSummary(built, flags.entry))
   })).pipe(
     Command.withDescription("Bundle and validate one named actor as a portable artifact."),
     Command.withExamples([
@@ -246,6 +278,10 @@ export const devCommand = Command.make("dev", {
     Flag.withDescription("The directory holding pushed actor databases. Defaults to TARDIGRADE_ACTOR_DATA."),
     Flag.optional
   ),
+  actorRefreshMillis: Flag.integer("actor-refresh-ms").pipe(
+    Flag.withDescription("Milliseconds to wait after a local actor change before refreshing the registry."),
+    Flag.withDefault(DEFAULT_ACTOR_REFRESH_MILLIS)
+  ),
   ui: Flag.string("ui").pipe(
     Flag.withDescription("The directory holding the built UI. Defaults to the build shipped beside this command."),
     Flag.optional
@@ -307,6 +343,7 @@ export const devCommand = Command.make("dev", {
       try: () => dev({
         config: config2,
         assets: stated(flags.ui),
+        actorRefreshMillis: flags.actorRefreshMillis,
         ...(flags.open ? { onListen: openBrowser } : {})
       }),
       catch: userErrorOf
@@ -346,7 +383,13 @@ export const runCommand = Command.make("run", {
     const id = stated(flags.id) ?? cli.mintId()
     const accepted = yield* call(() => client.append(thread, { type: "MessageReceived", id, text: flags.brief }))
     const view = yield* settle(client, accepted.thread, id, flags.poll, flags.timeout)
-    yield* Console.log(flags.json ? jsonOf(view) : turnLines(accepted.thread, view))
+    yield* Console.log(
+      flags.json
+        ? jsonOf(view)
+        : view.status === SETTLED
+        ? `${turnLines(accepted.thread, view)}\n\ntrace\n  ${traceUrlFor(client.baseUrl, client.actor, accepted.thread)}`
+        : turnLines(accepted.thread, view)
+    )
     if (view.status !== SETTLED) {
       return yield* Effect.fail(userErrorOf(`turn ${view.turn} on thread ${accepted.thread} is ${view.status}`))
     }
@@ -444,5 +487,5 @@ export const tdg = Command.make("tdg").pipe(
   Command.withDescription(
     "The tardigrade command. Every read is a projection of a durable log, and every failure is the server's own problem document."
   ),
-  Command.withSubcommands([setupCommand, buildCommand, pushCommand, devCommand, actorsCommand, runCommand, sendCommand, lsCommand, eventsCommand])
+  Command.withSubcommands([setupCommand, initCommand, buildCommand, pushCommand, devCommand, actorsCommand, runCommand, sendCommand, lsCommand, eventsCommand])
 )

package/src/cli/dev.ts

@@ -26,6 +26,10 @@ export const DEV_URL_HOST = "localhost"
 // occupied. The `--min-port` flag lets a caller narrow this range.
 export const DEFAULT_MIN_PORT = 1024
 
+// DEFAULT_ACTOR_REFRESH_MILLIS lets an atomic local push finish its directory swaps before tdg dev
+// reconciles the actor root. DevOptions and --actor-refresh-ms can replace it.
+export const DEFAULT_ACTOR_REFRESH_MILLIS = 50
+
 // The status that means the router matched nothing. It is the seam the UI is served through: the
 // declared routes answer first, and only a path none of them owns reaches the build.
 export const UNMATCHED = 404
@@ -110,6 +114,8 @@ export interface DevOptions {
   readonly assets?: string | undefined
   // The model seam, which a test binds to a scripted mind (apps/server/src/host.ts, ThreadsOptions).
   readonly threads?: ThreadsOptions | undefined
+  // actorRefreshMillis is the visible debounce applied to local actor-root changes.
+  readonly actorRefreshMillis?: number | undefined
   readonly disableLogger?: boolean | undefined
   readonly disableListenLog?: boolean | undefined
   // onListen receives the UI URL after the server owns its listening socket.
@@ -120,9 +126,16 @@ export interface DevOptions {
 // Layer rather than a running process, so the caller owns the scope and the process that stops
 // listening stops writing (apps/server/src/host.ts, layerThreads).
 export const dev = (options: DevOptions) => {
+  const actorRefreshMillis = options.actorRefreshMillis ?? DEFAULT_ACTOR_REFRESH_MILLIS
+  if (!Number.isInteger(actorRefreshMillis) || actorRefreshMillis < 0) {
+    throw new Error(`actor refresh must be a non-negative integer, got ${actorRefreshMillis}`)
+  }
   const root = resolveAssets(options.assets)
   const config = layerConfig(options.config)
-  const threads = Layer.provide(layerThreads(options.threads ?? {}), config)
+  const threads = Layer.provide(layerThreads({
+    ...options.threads,
+    actorRefresh: { debounceMillis: actorRefreshMillis }
+  }), config)
   // provideMerge rather than provide: the listening server stays visible in the layer's own
   // services, which is what lets a caller read the address it was given when it asked for port 0
   // (dev.test.ts).

package/src/cli/init.ts

@@ -0,0 +1,65 @@
+import { mkdir, writeFile } from "node:fs/promises"
+import { dirname, relative, resolve } from "node:path"
+
+import { actorTemplate } from "./template"
+import { runCommandFor, shellWord } from "./workflow"
+
+export const DEFAULT_ACTOR_ENTRY = "actor.ts"
+
+export interface InitActorOptions {
+  readonly cwd?: string
+  readonly directory?: string
+  readonly force?: boolean
+}
+
+export interface InitializedActor {
+  readonly name: string
+  readonly directory: string
+  readonly entry: string
+}
+
+export const defaultInitDirectory = (name: string): string => name
+
+const existsError = (error: unknown): boolean =>
+  typeof error === "object" && error !== null && "code" in error && error.code === "EEXIST"
+
+export const initActor = async (name: string, options: InitActorOptions = {}): Promise<InitializedActor> => {
+  const cwd = options.cwd ?? process.cwd()
+  const directory = resolve(cwd, options.directory ?? defaultInitDirectory(name))
+  const entry = resolve(directory, DEFAULT_ACTOR_ENTRY)
+  const source = await actorTemplate({ name })
+
+  await mkdir(dirname(entry), { recursive: true })
+  try {
+    await writeFile(entry, source, { encoding: "utf8", flag: options.force === true ? "w" : "wx" })
+  } catch (error) {
+    if (existsError(error)) {
+      throw new Error(`actor already exists at ${entry}. Choose another directory or pass --force.`)
+    }
+    throw error
+  }
+
+  return { name, directory, entry }
+}
+
+const shownPath = (cwd: string, path: string): string => {
+  const shown = relative(cwd, path)
+  return shown.length === 0 ? "." : shown
+}
+
+export const initSummary = (actor: InitializedActor, cwd: string = process.cwd()): string => {
+  const directory = shownPath(cwd, actor.directory)
+  const entry = shownPath(actor.directory, actor.entry)
+  return [
+    `created ${shownPath(cwd, actor.entry)}`,
+    "",
+    "next",
+    `  cd ${shellWord(directory)}`,
+    `  tdg build ${shellWord(entry)}`,
+    `  tdg push ${shellWord(entry)} --target local`,
+    "  tdg dev",
+    "",
+    "then, in another terminal",
+    `  ${runCommandFor(actor.name)}`
+  ].join("\n")
+}

package/src/cli/push.ts

@@ -5,6 +5,7 @@ import { join, resolve } from "node:path"
 import type { ActorArtifactManifest } from "tardie"
 
 import { ACTOR_MANIFEST_FILE, ACTOR_MODULE_FILE, buildActor, type BuildActorOptions, type BuiltActor } from "./build"
+import { runCommandFor } from "./workflow"
 
 export const DEFAULT_ACTOR_DIRECTORY = ".tardigrade/actors"
 export const PUSH_PATH = "/v1/actors"
@@ -98,10 +99,22 @@ export const pushActor = async (entry: string, options: PushActorOptions): Promi
   return options.target === "local" ? pushLocal(built, options) : pushHosted(built, options)
 }
 
-export const pushSummary = (pushed: PushedActor): string =>
-  [
+export const pushSummary = (pushed: PushedActor): string => {
+  const summary = [
     `pushed ${pushed.manifest.name}`,
     `to     ${pushed.target}`,
     `at     ${pushed.location}`,
     `hash   ${pushed.manifest.digest}`
-  ].join("\n")
+  ]
+  if (pushed.target === "local") {
+    summary.push(
+      "",
+      "next",
+      "  tdg dev",
+      "",
+      "then, in another terminal",
+      `  ${runCommandFor(pushed.manifest.name)}`
+    )
+  }
+  return summary.join("\n")
+}

package/src/cli/template.ts

@@ -0,0 +1,62 @@
+import { ACTOR_NAME_PATTERN } from "tardie"
+import { existsSync } from "node:fs"
+import { readFile } from "node:fs/promises"
+import { fileURLToPath } from "node:url"
+
+export interface ActorTemplateOptions {
+  readonly name: string
+  readonly instructions?: string
+}
+
+export const INSTALLED_ACTOR_TEMPLATE = "../../examples/quickstart/actor.ts"
+export const REPO_ACTOR_TEMPLATE = "../../../examples/quickstart/actor.ts"
+export const ACTOR_TEMPLATE_CANDIDATES: ReadonlyArray<string> = [INSTALLED_ACTOR_TEMPLATE, REPO_ACTOR_TEMPLATE]
+
+const templateLiteralOf = (value: string): string =>
+  value
+    .replaceAll("\\", "\\\\")
+    .replaceAll("`", "\\`")
+    .replaceAll("${", "\\${")
+
+const replaceExactlyOnce = (source: string, pattern: RegExp, replacement: string, field: string): string => {
+  const matches = source.match(pattern)
+  if (matches === null || matches.length !== 1) throw new Error(`quickstart template must contain one ${field}`)
+  return source.replace(pattern, replacement)
+}
+
+export const renderActorTemplate = (source: string, options: ActorTemplateOptions): string => {
+  if (!ACTOR_NAME_PATTERN.test(options.name)) {
+    throw new Error(`actor name must match ${String(ACTOR_NAME_PATTERN)}, got ${JSON.stringify(options.name)}`)
+  }
+
+  let rendered = replaceExactlyOnce(
+    source,
+    /^const actorName = .+$/gmu,
+    `const actorName = ${JSON.stringify(options.name)}`,
+    "actorName declaration"
+  )
+  if (options.instructions === undefined) return rendered
+
+  const instructions = options.instructions.trim()
+  if (instructions.length === 0) throw new Error("actor instructions must not be blank")
+  rendered = replaceExactlyOnce(
+    rendered,
+    /^const actorInstructions = `[\s\S]*?`\.trim\(\)$/gmu,
+    `const actorInstructions = \`\n${templateLiteralOf(instructions)}\n\`.trim()`,
+    "actorInstructions declaration"
+  )
+  return rendered
+}
+
+export const loadActorTemplate = async (candidates: ReadonlyArray<string>): Promise<string> => {
+  const found = candidates.find((candidate) => existsSync(candidate))
+  if (found === undefined) throw new Error(`quickstart template is missing. Looked in: ${candidates.join(", ")}`)
+  return readFile(found, "utf8")
+}
+
+export const actorTemplate = async (
+  options: ActorTemplateOptions,
+  candidates: ReadonlyArray<string> = ACTOR_TEMPLATE_CANDIDATES.map((candidate) =>
+    fileURLToPath(new URL(candidate, import.meta.url))
+  )
+): Promise<string> => renderActorTemplate(await loadActorTemplate(candidates), options)

package/src/cli/workflow.ts

@@ -0,0 +1,23 @@
+// DEFAULT_ONBOARDING_BRIEF is the first local run suggested after an actor is pushed.
+export const DEFAULT_ONBOARDING_BRIEF = "Read this repository and tell me what it does"
+
+// shellWord quotes a generated shell argument when spaces or shell punctuation make a bare word unsafe (workflow.test.ts).
+export const shellWord = (value: string): string =>
+  /^[A-Za-z0-9_./-]+$/u.test(value) ? value : `'${value.replaceAll("'", `'\\''`)}'`
+
+// runCommandFor renders the local quickstart command with its actor and brief stated.
+export const runCommandFor = (
+  actor: string,
+  brief: string = DEFAULT_ONBOARDING_BRIEF
+): string => `tdg run ${shellWord(brief)} --actor ${shellWord(actor)}`
+
+// traceUrlFor selects the actor and thread in the Voyager served at the API origin (apps/voyager/src/nav.ts, Route).
+export const traceUrlFor = (baseUrl: string, actor: string, thread: string): string => {
+  const url = new URL(baseUrl)
+  url.pathname = "/"
+  url.search = ""
+  url.hash = ""
+  url.searchParams.set("actor", actor)
+  url.searchParams.set("thread", thread)
+  return url.toString()
+}

package/src/server/host.ts

@@ -2,6 +2,7 @@ import { Clock, Context, Effect, Layer } from "effect"
 import { FetchHttpClient } from "effect/unstable/http"
 import { BunFileSystem, BunPath } from "@effect/platform-bun"
 import { createHash } from "node:crypto"
+import { watch, type FSWatcher } from "node:fs"
 import { mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises"
 import { join, resolve } from "node:path"
 import { pathToFileURL } from "node:url"
@@ -102,6 +103,12 @@ export interface ThreadsOptions {
   // derivation whole, which is how a test runs a scripted mind with no credentials
   // (host.test.ts). It is the one seam because Infer is the one place a turn leaves the process.
   readonly infer?: Layer.Layer<Infer>
+  // actorRefresh watches the actor root and reconciles its artifacts after the stated debounce.
+  // Absent keeps a hosted server's registry fixed except for PUT /v1/actors; tdg dev supplies it.
+  readonly actorRefresh?: {
+    readonly debounceMillis: number
+    readonly onError?: ((error: Error) => void) | undefined
+  } | undefined
 }
 
 interface ActorRuntime {
@@ -240,41 +247,91 @@ const make = (options: ThreadsOptions) =>
     const lane = layerLane(config, options)
     const runtimes = new Map<string, ActorRuntime>()
     const builtIn = assemblyOf()
+    const root = resolve(config.actors)
+    let mutations: Promise<void> = Promise.resolve()
+    const exclusive = <A>(operation: () => Promise<A>): Promise<A> => {
+      const result = mutations.then(operation, operation)
+      mutations = result.then(() => undefined, () => undefined)
+      return result
+    }
     const open = async (summary: ActorSummary, actor: Actor<ServerR>, log: string): Promise<ActorRuntime> => {
       const runtime = await runtimeOf(summary, actor, log, lane)
       runtimes.set(summary.name, runtime)
       return runtime
     }
+    const load = async (directory: string): Promise<{ readonly summary: ActorSummary; readonly actor: Actor<ServerR> }> => {
+      const artifact = await manifestOf(directory)
+      if (artifact.manifest.name === RESERVED_ACTOR) throw new Error(`${RESERVED_ACTOR} is reserved for the built-in actor`)
+      const definition = await definitionOf(join(directory, artifact.manifest.module), artifact.manifest)
+      return {
+        summary: { name: definition.name, builtIn: false, digest: artifact.manifest.digest },
+        actor: definition.actor
+      }
+    }
+    const replace = async (summary: ActorSummary, actor: Actor<ServerR>): Promise<void> => {
+      const current = runtimes.get(summary.name)
+      if (current?.summary.digest === summary.digest) return
+      if (current !== undefined) {
+        await current.close()
+        runtimes.delete(summary.name)
+      }
+      await open(summary, actor, join(resolve(config.actorData), `${summary.name}.sqlite`))
+    }
+    const synchronize = async (): Promise<void> => {
+      const entries = await readdir(root, { withFileTypes: true }).catch((error: NodeJS.ErrnoException) => {
+        if (error.code === "ENOENT") return []
+        throw error
+      })
+      const found = new Set<string>()
+      for (const entry of entries) {
+        if (!entry.isDirectory() || !ACTOR_NAME_PATTERN.test(entry.name)) continue
+        const loaded = await load(join(root, entry.name))
+        if (loaded.summary.name !== entry.name) throw new Error(`actor artifact name does not match directory ${JSON.stringify(entry.name)}`)
+        found.add(loaded.summary.name)
+        await replace(loaded.summary, loaded.actor)
+      }
+      for (const [name, runtime] of runtimes) {
+        if (name === RESERVED_ACTOR || found.has(name)) continue
+        await runtime.close()
+        runtimes.delete(name)
+      }
+    }
+    let watcher: FSWatcher | undefined
+    let refreshTimer: ReturnType<typeof setTimeout> | undefined
     yield* Effect.acquireRelease(
       Effect.promise(async () => {
         await open({ name: RESERVED_ACTOR, builtIn: true }, builtIn, config.db)
-        const root = resolve(config.actors)
-        const entries = await readdir(root, { withFileTypes: true }).catch((error: NodeJS.ErrnoException) => {
-          if (error.code === "ENOENT") return []
-          throw error
-        })
-        for (const entry of entries) {
-          if (!entry.isDirectory()) continue
-          const directory = join(root, entry.name)
-          const artifact = await manifestOf(directory)
-          if (artifact.manifest.name === RESERVED_ACTOR) throw new Error(`${RESERVED_ACTOR} is reserved for the built-in actor`)
-          const definition = await definitionOf(join(directory, artifact.manifest.module), artifact.manifest)
-          await open(
-            { name: definition.name, builtIn: false, digest: artifact.manifest.digest },
-            definition.actor,
-            join(resolve(config.actorData), `${definition.name}.sqlite`)
-          )
+        await synchronize()
+        if (options.actorRefresh !== undefined) {
+          const { debounceMillis } = options.actorRefresh
+          if (!Number.isInteger(debounceMillis) || debounceMillis < 0) {
+            throw new Error(`actor refresh debounce must be a non-negative integer, got ${debounceMillis}`)
+          }
+          await mkdir(root, { recursive: true })
+          const report = options.actorRefresh.onError ?? ((error: Error) => console.error(`actor refresh failed: ${error.message}`))
+          watcher = watch(root, () => {
+            if (refreshTimer !== undefined) clearTimeout(refreshTimer)
+            refreshTimer = setTimeout(() => {
+              refreshTimer = undefined
+              void exclusive(synchronize).catch((error: unknown) => report(error instanceof Error ? error : new Error(String(error))))
+            }, debounceMillis)
+          })
         }
         return runtimes
       }),
-      (opened) => Effect.promise(() => Promise.all([...opened.values()].map((runtime) => runtime.close())).then(() => undefined))
+      (opened) => Effect.promise(async () => {
+        watcher?.close()
+        if (refreshTimer !== undefined) clearTimeout(refreshTimer)
+        await mutations
+        await Promise.all([...opened.values()].map((runtime) => runtime.close()))
+      })
     )
 
     const selected = (name: string): ActorThreads | undefined => runtimes.get(name)?.threads
     const primary = selected(RESERVED_ACTOR)!
     const push = (artifact: ActorArtifact): Effect.Effect<ActorSummary, Error> =>
       Effect.tryPromise({
-        try: async () => {
+        try: () => exclusive(async () => {
           const manifest = artifact.manifest as ActorArtifactManifest
           if (manifest.schema !== ACTOR_ARTIFACT_VERSION) throw new Error(`unsupported actor artifact schema ${manifest.schema}`)
           if (!ACTOR_NAME_PATTERN.test(manifest.name)) throw new Error(`actor name must match ${String(ACTOR_NAME_PATTERN)}`)
@@ -282,7 +339,6 @@ const make = (options: ThreadsOptions) =>
           if (manifest.module !== "actor.mjs") throw new Error(`actor module must be ${JSON.stringify("actor.mjs")}`)
           const actual = digestOf(artifact.module)
           if (actual !== manifest.digest) throw new Error(`actor artifact digest mismatch: expected ${manifest.digest}, got ${actual}`)
-          const root = resolve(config.actors)
           const destination = join(root, manifest.name)
           const temporary = `${destination}.incoming`
           const previous = `${destination}.previous`
@@ -313,7 +369,7 @@ const make = (options: ThreadsOptions) =>
             await rm(temporary, { recursive: true, force: true })
             throw error
           }
-        },
+        }),
         catch: (error) => error instanceof Error ? error : new Error(String(error))
       })