typeclaw 0.1.4 → 0.1.6

package/src/doctor/checks.ts

@@ -23,8 +23,6 @@ import { buildGitignore, GITIGNORE_FILE } from '@/init/gitignore'
 
 import type { DoctorCheck } from './types'
 
-const REQUIRED_DIRS = ['workspace', 'sessions', '.agents/skills', 'mounts', 'packages'] as const
-
 export function buildStaticChecks(opts: { dockerExec?: DockerExec } = {}): DoctorCheck[] {
   const dockerExec = opts.dockerExec ?? defaultDockerExec
 
@@ -32,12 +30,12 @@ export function buildStaticChecks(opts: { dockerExec?: DockerExec } = {}): Docto
     dockerDaemon(dockerExec),
     bunRuntime(),
     agentFolderInitialized(),
-    agentFolderRequiredDirs(),
     agentFolderDockerfileTemplate(),
     agentFolderGitignoreTemplate(),
     agentFolderNodeModules(),
     agentFolderGitRepo(),
     configValid(),
+    configBundledProfiles(),
     hostdHomeWritable(),
     hostdReachable(),
     hostdRegistration(),
@@ -103,36 +101,6 @@ function agentFolderInitialized(): DoctorCheck {
   }
 }
 
-function agentFolderRequiredDirs(): DoctorCheck {
-  return {
-    name: 'agent-folder.required-dirs',
-    category: 'agent-folder',
-    description: 'required agent directories exist',
-    applies: (ctx) => ctx.hasAgentFolder,
-    async run(ctx) {
-      const missing = REQUIRED_DIRS.filter((d) => !existsSync(join(ctx.cwd, d)))
-      if (missing.length === 0) return { status: 'ok', message: 'all required directories present' }
-      return {
-        status: 'warning',
-        message: `${missing.length} required ${missing.length === 1 ? 'directory' : 'directories'} missing`,
-        details: missing.map((d) => `missing: ${d}/`),
-        fix: {
-          description: `Create the missing directories (${missing.map((d) => `${d}/`).join(', ')}).`,
-          autoFix: async () => {
-            for (const d of missing) {
-              mkdirSync(join(ctx.cwd, d), { recursive: true })
-            }
-            return {
-              summary: `created ${missing.map((d) => `${d}/`).join(', ')}`,
-              changedPaths: missing.map((d) => `${d}/`),
-            }
-          },
-        },
-      }
-    },
-  }
-}
-
 function agentFolderDockerfileTemplate(): DoctorCheck {
   return {
     name: 'agent-folder.dockerfile-managed',
@@ -247,6 +215,55 @@ function configValid(): DoctorCheck {
   }
 }
 
+// Warns (not errors) when a model profile that a bundled subagent prefers is
+// absent from `models`. Bundled subagents fall back to `default` silently
+// today, but the operator likely declared a `fast`/`deep`/`vision` model in
+// the design discussion's tier scheme expecting the bundled subagents to
+// pick them up. This check surfaces the gap once at `typeclaw doctor` time
+// instead of leaving it buried in container logs (where the rate-limited
+// fallback warning lives).
+//
+// We deliberately limit this to known bundled profiles (memory-logger=fast,
+// dreaming=deep, multimodal-looker=vision). Plugin-contributed subagents
+// would require loading the plugin registry — a heavyweight async path
+// that doesn't belong in doctor's static check surface.
+const BUNDLED_PROFILES: ReadonlyArray<{ profile: string; subagent: string }> = [
+  { profile: 'fast', subagent: 'memory-logger' },
+  { profile: 'deep', subagent: 'dreaming' },
+  { profile: 'vision', subagent: 'multimodal-looker (via look_at tool)' },
+]
+
+function configBundledProfiles(): DoctorCheck {
+  return {
+    name: 'config.bundled-profiles',
+    category: 'config',
+    description: 'bundled subagent profiles (`fast`, `deep`, `vision`) declared in models',
+    applies: (ctx) => ctx.hasAgentFolder,
+    async run(ctx) {
+      const validation = validateConfig(ctx.cwd)
+      if (!validation.ok) {
+        return { status: 'ok', message: 'skipped (config.valid will report the underlying error)' }
+      }
+      const config = loadConfigSync(ctx.cwd)
+      const declared = new Set(Object.keys(config.models))
+      const missing = BUNDLED_PROFILES.filter((p) => !declared.has(p.profile))
+      if (missing.length === 0) {
+        return { status: 'ok', message: 'all bundled subagent profiles declared' }
+      }
+      return {
+        status: 'warning',
+        message: `${missing.length} bundled profile(s) missing; will fall back to \`default\``,
+        details: missing.map(
+          (m) => `${m.profile}: used by ${m.subagent}; declare \`models.${m.profile}\` in typeclaw.json to override`,
+        ),
+        fix: {
+          description: 'Add the missing profile(s) under `models` in typeclaw.json. See the typeclaw-config skill.',
+        },
+      }
+    },
+  }
+}
+
 function hostdHomeWritable(): DoctorCheck {
   return {
     name: 'hostd.home-writable',
@@ -390,7 +407,7 @@ function loadConfigStrictForTemplate(
   const result = validateConfig(cwd)
   if (!result.ok) return null
   const cfg = loadConfigSync(cwd)
-  return { dockerfile: cfg.dockerfile, gitignore: cfg.gitignore }
+  return { dockerfile: cfg.docker.file, gitignore: cfg.git.ignore }
 }
 
 async function safeRead(path: string): Promise<string | null> {

package/src/doctor/plugin-bridge.ts

@@ -1,4 +1,4 @@
-import { resolveHostPort } from '@/container'
+import { resolveHostPort, resolveTuiToken } from '@/container'
 import type { ClientMessage, DoctorCheckPayload, DoctorFixPayload, ServerMessage } from '@/shared'
 
 export type PluginBridgeOptions = {
@@ -80,12 +80,14 @@ async function dial(opts: PluginBridgeOptions): Promise<DialResult> {
   if (url === undefined) {
     try {
       const port = await resolveHostPort({ cwd: opts.cwd })
-      url = `ws://localhost:${port}`
+      const token = await resolveTuiToken({ cwd: opts.cwd })
+      url = buildBridgeUrl(port, token)
     } catch (err) {
       return { kind: 'unreachable', reason: err instanceof Error ? err.message : String(err) }
     }
   }
   const ws = new WebSocket(url)
+  const displayUrl = redactUrl(url)
   try {
     await new Promise<void>((resolve, reject) => {
       // `timer` is declared up front so `cleanup` can reference it without
@@ -97,6 +99,7 @@ async function dial(opts: PluginBridgeOptions): Promise<DialResult> {
         if (timer !== undefined) clearTimeout(timer)
         ws.removeEventListener('open', onOpen)
         ws.removeEventListener('error', onError)
+        ws.removeEventListener('close', onClose)
       }
       const onOpen = () => {
         cleanup()
@@ -104,7 +107,11 @@ async function dial(opts: PluginBridgeOptions): Promise<DialResult> {
       }
       const onError = (err: unknown) => {
         cleanup()
-        reject(err instanceof Error ? err : new Error(`failed to connect to ${url}`))
+        reject(new Error(`failed to connect to ${displayUrl}: ${err instanceof Error ? err.message : String(err)}`))
+      }
+      const onClose = () => {
+        cleanup()
+        reject(new Error(`connection to ${displayUrl} closed before opening`))
       }
       // Bun's WebSocket has no built-in connect timeout. Without this, a TCP
       // handshake that completes but never produces an Upgrade response
@@ -117,10 +124,11 @@ async function dial(opts: PluginBridgeOptions): Promise<DialResult> {
         try {
           ws.close()
         } catch {}
-        reject(new Error(`websocket connect timeout after ${timeoutMs}ms`))
+        reject(new Error(`timed out connecting to ${displayUrl} after ${timeoutMs}ms`))
       }, timeoutMs)
       ws.addEventListener('open', onOpen, { once: true })
       ws.addEventListener('error', onError, { once: true })
+      ws.addEventListener('close', onClose, { once: true })
     })
   } catch (err) {
     return { kind: 'unreachable', reason: err instanceof Error ? err.message : String(err) }
@@ -128,6 +136,22 @@ async function dial(opts: PluginBridgeOptions): Promise<DialResult> {
   return { kind: 'ok', ws, timeoutMs }
 }
 
+function buildBridgeUrl(port: number, token: string | null): string {
+  const url = new URL(`ws://127.0.0.1:${port}`)
+  if (token !== null) url.searchParams.set('token', token)
+  return url.toString()
+}
+
+function redactUrl(url: string): string {
+  try {
+    const parsed = new URL(url)
+    if (parsed.searchParams.has('token')) parsed.searchParams.set('token', '<redacted>')
+    return parsed.toString()
+  } catch {
+    return url
+  }
+}
+
 async function withRequest<R extends { kind: string }>(
   ws: WebSocket,
   timeoutMs: number,

package/src/git/system-commit.ts

@@ -0,0 +1,103 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+// Commits TypeClaw-owned tracked files (.gitignore, package.json,
+// typeclaw.json) if any are dirty in git. Skips silently when the agent
+// folder is not a git repo, when Bun is unavailable, or when every named
+// file is clean. Uses the user's global git config for authorship —
+// TypeClaw does not impersonate the user here.
+//
+// Accepts a single file or an array; the array form produces a single
+// atomic commit covering all listed paths (used for migrations that touch
+// multiple files together, e.g. enabling bun workspaces writes both
+// package.json and packages/.gitkeep in one commit).
+//
+// Lives under src/git/ rather than src/container/ because both the
+// host-stage launcher (typeclaw start) and src/config/config.ts (called
+// from every entry point that reads typeclaw.json, host AND container)
+// need to commit migration artifacts. Putting it in src/container/ would
+// pull container-level imports into the config module and create a
+// circular dependency at the package boundary.
+export async function commitSystemFile(cwd: string, file: string | readonly string[], message: string): Promise<void> {
+  const files = typeof file === 'string' ? [file] : file
+  if (files.length === 0) return
+
+  const bun = getBunAsync()
+  if (!bun) return
+  if (!existsSync(join(cwd, '.git'))) return
+
+  const status = bun.spawn({
+    cmd: ['git', 'status', '--porcelain', '--', ...files],
+    cwd,
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  if ((await status.exited) !== 0) return
+  const dirty = (await new Response(status.stdout).text()).trim().length > 0
+  if (!dirty) return
+
+  const add = bun.spawn({ cmd: ['git', 'add', '--', ...files], cwd, stdout: 'pipe', stderr: 'pipe' })
+  if ((await add.exited) !== 0) return
+
+  const commit = bun.spawn({
+    cmd: ['git', 'commit', '-m', message, '--only', '--', ...files],
+    cwd,
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  await commit.exited
+}
+
+// Synchronous variant for callers that already hold a synchronous codepath
+// — specifically `persistMigratedConfig` in src/config/config.ts. The
+// migration write is itself synchronous (writeFileSync) and the call sites
+// (loadConfigSync, validateConfig, loadPluginConfigsSync) are sync, so we
+// cannot await an async commit without forcing them all to become async,
+// which would ripple into hundreds of call sites across the codebase.
+//
+// The commit overhead (~10-50ms) is paid exactly once per agent folder
+// per legacy form: after the first call rewrites the file to canonical
+// shape, subsequent migrateLegacyConfigShape calls return changed=false
+// and this codepath is unreachable. On canonical folders (the common
+// case) this function is never called at all.
+//
+// Same skip semantics as the async variant — no-op when the folder is not
+// a git repo, when Bun is unavailable, or when the file is clean.
+export function commitSystemFileSync(cwd: string, file: string | readonly string[], message: string): void {
+  const files = typeof file === 'string' ? [file] : file
+  if (files.length === 0) return
+
+  const bun = getBunSync()
+  if (!bun) return
+  if (!existsSync(join(cwd, '.git'))) return
+
+  const status = bun.spawnSync({
+    cmd: ['git', 'status', '--porcelain', '--', ...files],
+    cwd,
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  if (status.exitCode !== 0) return
+  if (new TextDecoder().decode(status.stdout).trim().length === 0) return
+
+  const add = bun.spawnSync({ cmd: ['git', 'add', '--', ...files], cwd, stdout: 'pipe', stderr: 'pipe' })
+  if (add.exitCode !== 0) return
+
+  bun.spawnSync({
+    cmd: ['git', 'commit', '-m', message, '--only', '--', ...files],
+    cwd,
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+}
+
+// Bun-availability shims kept tight to the two functions so the module
+// has no module-level side effects (matters for the sync codepath, which
+// is called during typeclaw.json reads on hot import).
+function getBunAsync(): { spawn: typeof Bun.spawn } | undefined {
+  return (globalThis as { Bun?: { spawn: typeof Bun.spawn } }).Bun
+}
+
+function getBunSync(): { spawnSync: typeof Bun.spawnSync } | undefined {
+  return (globalThis as { Bun?: { spawnSync: typeof Bun.spawnSync } }).Bun
+}

package/src/hostd/daemon.ts

@@ -11,6 +11,7 @@ import { kakaoChannelBlockSchema } from '@/secrets/schema'
 import { SecretsBackend } from '@/secrets/storage'
 
 import { isDaemonReachable } from './client'
+import type { KakaoRenewalCallbacks, KakaoRenewalLogEvent } from './kakao-renewal-manager'
 import { ensureDirs, registrationFilePath, registrationsDir, socketPath } from './paths'
 import type {
   HttpInfoResult,
@@ -54,6 +55,11 @@ export type DaemonOptions = {
   // fields trigger broker spawn alongside supervisor registration. Tests omit
   // it to keep the broker out of unrelated suites.
   portbroker?: PortbrokerCallbacks
+  // KakaoTalk credential renewal capability. When provided, the daemon
+  // starts a per-container daily renewal tick on register and stops it on
+  // deregister. Omit to disable in tests / when the agent has no kakaotalk
+  // channel configured.
+  kakaoRenewal?: KakaoRenewalCallbacks
 }
 
 export type RestartPreflight = (input: {
@@ -94,6 +100,7 @@ export type DaemonLogEvent =
   | { kind: 'shutdown-requested' }
   | { kind: 'port-forward-event'; event: PortForwardEvent }
   | { kind: 'tailscale-serve-event'; event: TailscaleServeEvent }
+  | KakaoRenewalLogEvent
 
 export type Daemon = {
   registered: () => string[]
@@ -284,6 +291,9 @@ export async function startDaemon(opts: DaemonOptions = {}): Promise<Daemon> {
         onTailscaleServeEvent: (event) => log({ kind: 'tailscale-serve-event', event }),
       })
     }
+    if (opts.kakaoRenewal) {
+      opts.kakaoRenewal.start({ containerName: payload.containerName, cwd: payload.cwd })
+    }
   }
 
   const handleRegister = async (req: RegisterPayload): Promise<RpcResponse> => {
@@ -309,6 +319,7 @@ export async function startDaemon(opts: DaemonOptions = {}): Promise<Daemon> {
       restartTokens.delete(req.containerName)
       gcMisses.delete(req.containerName)
       if (opts.portbroker) await opts.portbroker.stop(req.containerName, 'deregistered').catch(() => {})
+      if (opts.kakaoRenewal) await opts.kakaoRenewal.stop(req.containerName).catch(() => {})
       await removeRegistrationFile(req.containerName)
       if (hadCwd) log({ kind: 'deregister', containerName: req.containerName, reason: 'requested' })
       return { ok: true }
@@ -574,6 +585,7 @@ export async function startDaemon(opts: DaemonOptions = {}): Promise<Daemon> {
         const hadCwd = cwds.delete(name)
         restartTokens.delete(name)
         if (opts.portbroker) await opts.portbroker.stop(name, 'deregistered').catch(() => {})
+        if (opts.kakaoRenewal) await opts.kakaoRenewal.stop(name).catch(() => {})
         await removeRegistrationFile(name)
         if (hadCwd) log({ kind: 'deregister', containerName: name, reason: 'gone' })
         return { ok: true }
@@ -601,6 +613,10 @@ export async function startDaemon(opts: DaemonOptions = {}): Promise<Daemon> {
         const names = Array.from(cwds.keys())
         await Promise.allSettled(names.map((n) => opts.portbroker!.stop(n, 'broker-stopped')))
       }
+      if (opts.kakaoRenewal) {
+        const names = Array.from(cwds.keys())
+        await Promise.allSettled(names.map((n) => opts.kakaoRenewal!.stop(n)))
+      }
       cwds.clear()
       restartTokens.clear()
       try {

package/src/hostd/kakao-renewal-manager.ts

@@ -0,0 +1,223 @@
+import { renewCurrentAccount, type AttemptLoginFn } from '@/secrets/kakao-renewal'
+import { createKeyStore, type KeyStore } from '@/secrets/keys'
+
+import { keysDir } from './paths'
+
+const DEFAULT_TICK_INTERVAL_MS = 24 * 60 * 60 * 1000
+
+export type KakaoRenewalCallbacks = {
+  start: (input: KakaoRenewalStartInput) => void
+  stop: (containerName: string) => Promise<void>
+  drain: () => Promise<void>
+}
+
+export type KakaoRenewalStartInput = {
+  containerName: string
+  cwd: string
+}
+
+export type KakaoRenewalLogEvent =
+  | { kind: 'kakao-renewal-tick-start'; containerName: string }
+  | { kind: 'kakao-renewal-tick-skipped'; containerName: string; reason: string; ageMs?: number }
+  | { kind: 'kakao-renewal-tick-ok'; containerName: string; accountId: string; previousUpdatedAt: string }
+  | {
+      kind: 'kakao-renewal-tick-reauth-required'
+      containerName: string
+      accountId: string
+      reason: string
+      message: string
+    }
+  | { kind: 'kakao-renewal-tick-transient-failure'; containerName: string; accountId: string; reason: string }
+  | { kind: 'kakao-renewal-tick-error'; containerName: string; error: string }
+  | { kind: 'kakao-renewal-restart-scheduled'; containerName: string; accountId: string }
+  | { kind: 'kakao-renewal-restart-failed'; containerName: string; accountId: string; reason: string }
+
+export type KakaoRenewalManagerOptions = {
+  onLog?: (event: KakaoRenewalLogEvent) => void
+  tickIntervalMs?: number
+  keyStoreFactory?: () => KeyStore
+  attemptLogin?: AttemptLoginFn
+  schedule?: (fn: () => void, intervalMs: number) => { stop: () => void }
+  // Invoked after a successful renewal so the host can restart the container
+  // and the in-memory adapter picks up the fresh tokens. Without this, the
+  // cron writes new tokens to secrets.json but the live LOCO client keeps the
+  // old token in its closure and still hits 401 at the ~7-day wall. Production
+  // wires this to the same restart path the `restart` RPC uses; tests can
+  // observe it via a fake.
+  onRenewalOk?: (input: { containerName: string; cwd: string; accountId: string }) => Promise<void>
+  // Optional predicate: only start the renewal cron for containers whose
+  // `typeclaw.json` actually has a `channels.kakaotalk` block. Without this,
+  // every typeclaw agent on the host emits daily `no_account` skip logs.
+  shouldRenew?: (input: KakaoRenewalStartInput) => boolean
+}
+
+// Per-container daily renewal tick. Mirrors portbroker-manager.ts: hostd calls
+// start() on register and stop() on deregister, and the manager owns timer
+// lifecycle plus the actual renewal work. The keystore lives on the host
+// (~/.typeclaw/keys/<name>.key), unreachable from inside the container —
+// that's load-bearing for encryption.ts's threat model.
+export function createKakaoRenewalManager(opts: KakaoRenewalManagerOptions = {}): KakaoRenewalCallbacks {
+  const intervalMs = opts.tickIntervalMs ?? DEFAULT_TICK_INTERVAL_MS
+  const keyStore = (opts.keyStoreFactory ?? (() => createKeyStore({ keysDir: keysDir() })))()
+  const log = opts.onLog ?? (() => {})
+  const schedule =
+    opts.schedule ??
+    ((fn: () => void, ms: number) => {
+      const handle = setInterval(fn, ms)
+      return { stop: () => clearInterval(handle) }
+    })
+
+  const timers = new Map<string, { stop: () => void }>()
+  // Track the latest registration input per container so a re-register
+  // arriving during an in-flight tick can both (a) prevent the in-flight tick
+  // from acting on stale cwd, and (b) trigger a fresh tick once the in-flight
+  // one finishes. The Map's value is the most recent input.
+  const latestInput = new Map<string, KakaoRenewalStartInput>()
+  // Track in-flight tick promises per container so stop()/drain() can await
+  // them. Without this, daemon shutdown abandons an in-flight attemptLogin
+  // HTTPS request mid-write.
+  const inFlight = new Map<string, Promise<void>>()
+  // Pending immediate-tick request: set when start() is called while a tick
+  // is in flight, so we re-fire one tick after the in-flight settles.
+  const pendingRerun = new Set<string>()
+
+  const runTick = async (input: KakaoRenewalStartInput): Promise<void> => {
+    log({ kind: 'kakao-renewal-tick-start', containerName: input.containerName })
+    try {
+      const result = await renewCurrentAccount({
+        containerName: input.containerName,
+        agentDir: input.cwd,
+        keyStore,
+        ...(opts.attemptLogin ? { attemptLogin: opts.attemptLogin } : {}),
+      })
+      if (result.kind === 'skipped') {
+        log({
+          kind: 'kakao-renewal-tick-skipped',
+          containerName: input.containerName,
+          reason: result.reason,
+          ...(result.ageMs !== undefined ? { ageMs: result.ageMs } : {}),
+        })
+      } else if (result.kind === 'ok') {
+        log({
+          kind: 'kakao-renewal-tick-ok',
+          containerName: input.containerName,
+          accountId: result.account_id,
+          previousUpdatedAt: result.previousUpdatedAt,
+        })
+        if (opts.onRenewalOk) {
+          log({
+            kind: 'kakao-renewal-restart-scheduled',
+            containerName: input.containerName,
+            accountId: result.account_id,
+          })
+          try {
+            await opts.onRenewalOk({
+              containerName: input.containerName,
+              cwd: input.cwd,
+              accountId: result.account_id,
+            })
+          } catch (err) {
+            log({
+              kind: 'kakao-renewal-restart-failed',
+              containerName: input.containerName,
+              accountId: result.account_id,
+              reason: err instanceof Error ? err.message : String(err),
+            })
+          }
+        }
+      } else if (result.kind === 'reauth_required') {
+        log({
+          kind: 'kakao-renewal-tick-reauth-required',
+          containerName: input.containerName,
+          accountId: result.account_id,
+          reason: result.reason,
+          message: result.message,
+        })
+      } else {
+        log({
+          kind: 'kakao-renewal-tick-transient-failure',
+          containerName: input.containerName,
+          accountId: result.account_id,
+          reason: result.reason,
+        })
+      }
+    } catch (err) {
+      // Defensive: renewCurrentAccount's contract is to return a structured
+      // result, but a malformed secrets.json or a disk error could surface
+      // here. Log and move on — the next tick retries.
+      log({
+        kind: 'kakao-renewal-tick-error',
+        containerName: input.containerName,
+        error: err instanceof Error ? err.message : String(err),
+      })
+    }
+  }
+
+  // Single-flight per container: dedupe overlapping ticks, but if a new
+  // tick request arrives while one is in flight, queue ONE rerun so the new
+  // registration's cwd (or a manual nudge) gets a chance after the in-flight
+  // settles. The Promise stored in inFlight resolves only after any queued
+  // rerun also completes, so stop()/drain() awaiting inFlight is enough to
+  // observe a quiescent manager.
+  const scheduleTick = (containerName: string): Promise<void> => {
+    const existing = inFlight.get(containerName)
+    if (existing) {
+      pendingRerun.add(containerName)
+      return existing
+    }
+    const promise = (async () => {
+      // Loop until no rerun was queued during this tick, so the LAST input
+      // recorded for the container is the one we end on. This handles the
+      // re-register-while-in-flight + cwd-change case described in the
+      // pendingRerun comment above.
+      while (true) {
+        const input = latestInput.get(containerName)
+        if (!input) return
+        await runTick(input)
+        if (!pendingRerun.has(containerName)) return
+        pendingRerun.delete(containerName)
+      }
+    })().finally(() => {
+      inFlight.delete(containerName)
+      pendingRerun.delete(containerName)
+    })
+    inFlight.set(containerName, promise)
+    return promise
+  }
+
+  return {
+    start(input: KakaoRenewalStartInput): void {
+      if (opts.shouldRenew && !opts.shouldRenew(input)) return
+      const existing = timers.get(input.containerName)
+      if (existing) existing.stop()
+      latestInput.set(input.containerName, input)
+      const handle = schedule(() => {
+        void scheduleTick(input.containerName)
+      }, intervalMs)
+      timers.set(input.containerName, handle)
+      void scheduleTick(input.containerName)
+    },
+
+    async stop(containerName: string): Promise<void> {
+      const handle = timers.get(containerName)
+      if (handle) {
+        timers.delete(containerName)
+        handle.stop()
+      }
+      latestInput.delete(containerName)
+      // Await any in-flight tick before resolving so the caller can rely on
+      // "stop returned → no work outstanding". Daemon shutdown depends on
+      // this; without it, a mid-tick `attemptLogin` HTTPS call is abandoned.
+      const promise = inFlight.get(containerName)
+      if (promise) await promise.catch(() => {})
+    },
+
+    async drain(): Promise<void> {
+      for (const [, handle] of timers) handle.stop()
+      timers.clear()
+      latestInput.clear()
+      const promises = Array.from(inFlight.values())
+      await Promise.allSettled(promises)
+    },
+  }
+}

package/src/hostd/paths.ts

@@ -9,6 +9,7 @@ import { join } from 'node:path'
 const CONTAINER_HOST_RUN_DIR = '/run/typeclaw-host'
 const SOCKET_FILE = 'hostd.sock'
 const REGISTRATIONS_DIR = 'registrations'
+const KEYS_DIR = 'keys'
 
 // Defense-in-depth: containerName arrives from RPC payloads (some of which
 // originate inside the container). Docker already forbids slashes and most
@@ -51,6 +52,10 @@ export function registrationsDir(): string {
   return join(runDir(), REGISTRATIONS_DIR)
 }
 
+export function keysDir(): string {
+  return join(homeRoot(), KEYS_DIR)
+}
+
 // Throws on any name that could traverse out of registrationsDir() or
 // confuse the filesystem. Caller's responsibility to handle the error;
 // don't catch-and-ignore — an invalid name is a protocol violation.
@@ -76,7 +81,9 @@ export async function ensureDirs(): Promise<void> {
   await mkdir(runDir(), { recursive: true })
   await mkdir(logDir(), { recursive: true })
   await mkdir(registrationsDir(), { recursive: true })
+  await mkdir(keysDir(), { recursive: true })
   await chmod(runDir(), 0o700).catch(() => {})
   await chmod(logDir(), 0o700).catch(() => {})
   await chmod(registrationsDir(), 0o700).catch(() => {})
+  await chmod(keysDir(), 0o700).catch(() => {})
 }