@huynle/hub 0.8.0 → 0.8.1

package/src/spoke/localhub.ts

@@ -10,7 +10,9 @@ import path from "node:path"
 import { fileURLToPath } from "node:url"
 import { hubEnv } from "../env"
 import { isLoopbackURL } from "../loopback"
-import { APP_DIR, legacyPaths, migrateFirst, stateBase } from "../migrate"
+import { migrateStateDir, resolveHubStateDir, stateLegacyPaths } from "../migrate"
+
+const CONCIERGE_LOCK = "concierge-sessions.json"
 
 export interface ChildLike {
   readonly pid?: number
@@ -23,7 +25,7 @@ export type SpawnLike = (command: string, args: readonly string[], options: obje
 
 export interface LocalHubOptions {
   /**
-   * Where hub.pid and hub.log live (default $HUB_STATE_DIR or ~/.local/state/hub, migrated from
+   * Where hub.pid and hub.log live (default $HUB_STATE_DIR, else $XDG_STATE_HOME/hub or ~/.local/state/hub, migrated from
    * ~/.local/state/opencode-hub or opencode-voice first so the hub does not find a fresh, empty state directory).
    */
   readonly stateDir?: string
@@ -86,7 +88,15 @@ export function hubScript(root: string = repoRoot()): string {
 }
 
 export function defaultStateDir(env: Readonly<Record<string, string | undefined>> = process.env, home: string = homedir()): string {
-  return hubEnv(env).HUB_STATE_DIR || path.join(stateBase(home), APP_DIR)
+  return resolveHubStateDir(env, home).dir
+}
+
+/** The Concierge lock file (written in the state dir) and the other default places' lock files (read too: fail closed). */
+export function conciergeLockFiles(env: Readonly<Record<string, string | undefined>> = process.env, home: string = homedir()): { file: string; read: string[] } {
+  const { candidates, source } = resolveHubStateDir(env, home)
+  const [dir, ...others] = candidates
+  // An explicit HUB_STATE_DIR is an isolated instance (a preview or a test): it never reads the user's default dirs.
+  return { file: path.join(dir!, CONCIERGE_LOCK), read: source === "env" ? [] : others.map((d) => path.join(d, CONCIERGE_LOCK)) }
 }
 
 /** The runtime for this process: probes the real executable, PATH and home directory. */
@@ -152,7 +162,7 @@ export async function ensureLocalHub(server: string, options: LocalHubOptions =
   if (!(options.webBuilt ?? hasWebBuild)(root)) return { status: "failed", error: WEB_NOT_BUILT }
 
   if (options.stateDir === undefined && !hubEnv(env).HUB_STATE_DIR) {
-    migrateFirst(legacyPaths(stateBase(home)), stateDir, { skip: ["hub.pid"], ...(options.log ? { log: options.log } : {}) })
+    migrateStateDir(stateLegacyPaths(env, home), stateDir, { skip: ["hub.pid"], ...(options.log ? { log: options.log } : {}) })
   }
   mkdirSync(stateDir, { recursive: true, mode: 0o700 })
 

package/src/spoke/locations.ts

@@ -10,6 +10,7 @@ export interface PermissionLocation {
   get(input: { sessionID: string; requestID: string }): Promise<unknown>
   /** `message`: a reject's reason (OpenCode's reply message). */
   reply(input: { sessionID: string; requestID: string; decision: PermissionDecision; message?: string }): Promise<unknown>
+  vcs?: { diff(): Promise<ReadonlyArray<unknown>>; branch(): Promise<string | undefined> }
 }
 
 /**
@@ -33,3 +34,42 @@ export async function replyPermission(
   }
   return "gone"
 }
+
+/** A directory's branch and working-copy changes (undefined: nothing could read them). */
+export interface VcsReader {
+  diff(directory: string): Promise<ReadonlyArray<unknown> | undefined>
+  branch(directory: string): Promise<string | undefined>
+}
+
+/**
+ * Reads a directory's VCS state through the plugin instance whose location is that directory, else the own
+ * server's API (which honours the location), else not at all. OpenCode's plugin vcs API answers for the
+ * instance's own location whatever location is passed, so the first instance (the background service's is
+ * its $HOME) would report another directory's branch and changes. A read that takes longer than `timeoutMs` (a hung
+ * server) answers undefined, so the session summary goes on without branch and changes.
+ */
+/** How long a branch or changes read may take before the summary goes on without it (a hung server). */
+export const VCS_READ_TIMEOUT_MS = 5_000
+
+/** The value, or undefined once `ms` passed (the read is left to finish on its own). */
+function within<T>(read: Promise<T | undefined>, ms: number): Promise<T | undefined> {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const late = new Promise<undefined>((resolve) => {
+    timer = setTimeout(() => resolve(undefined), ms)
+  })
+  return Promise.race([read.catch(() => undefined), late]).finally(() => clearTimeout(timer))
+}
+
+export function vcsReader(locations: () => readonly PermissionLocation[], server: () => Promise<VcsReader | undefined>, timeoutMs: number = VCS_READ_TIMEOUT_MS): VcsReader {
+  const local = (directory: string) => locations().find((l) => l.directory === directory && l.vcs)?.vcs
+  return {
+    diff: async (directory) => {
+      const vcs = local(directory)
+      return within(vcs ? vcs.diff() : server().then((reader) => reader?.diff(directory)), timeoutMs)
+    },
+    branch: async (directory) => {
+      const vcs = local(directory)
+      return within(vcs ? vcs.branch() : server().then((reader) => reader?.branch(directory)), timeoutMs)
+    },
+  }
+}

package/src/spoke/session-context.ts

@@ -16,7 +16,7 @@
 // the plugin's state dir (lockFile), so a restarted OpenCode locks the session before the hub reconnects. The agent
 // a locked session was last seen on is reported to the hub (SessionInfo.agent), which suspends a Concierge found on
 // another agent.
-import { mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs"
+import { closeSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs"
 import path from "node:path"
 import { CONCIERGE_TOOLS, SESSION_CONTEXT_KEYS, type SessionContextRequest, type SessionContextResult, toolDenied } from "../../packages/protocol/src/concierge.ts"
 
@@ -43,6 +43,62 @@ export interface SessionContextsOptions {
   readonly maxSessions?: number
   /** Where locked session IDs persist (the plugin's state dir); in memory only without it. */
   readonly lockFile?: string
+  /** (FX-07) How long a write waits for the other processes' exclusive lock before it writes anyway. */
+  readonly lockWaitMs?: number
+  /**
+   * Other lock files read (never written): the other default state dir places (FX-08: a lock written before an
+   * upgrade moved the state dir still locks the session; fail closed).
+   */
+  readonly readLockFiles?: readonly string[]
+}
+
+/** (FX-07) A `<lockFile>.lock` older than this belongs to a process that died while writing: it is broken. */
+const WRITE_LOCK_STALE_MS = 10_000
+const WRITE_LOCK_WAIT_MS = 2_000
+const pause = (ms: number) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms)
+
+/**
+ * (FX-07) Runs `write` holding `<file>.lock` (created exclusively), so the read-merge-write of every OpenCode process
+ * on the machine is serialized and none drops another's locks. A stale lock (its holder died) is broken; after
+ * `waitMs` the write runs anyway (the lock still holds in this process, and the write merges what it reads).
+ */
+function underWriteLock(file: string, waitMs: number, write: () => void): void {
+  const lock = `${file}.lock`
+  const deadline = Date.now() + waitMs
+  let held = false
+  for (;;) {
+    try {
+      closeSync(openSync(lock, "wx", 0o600))
+      held = true
+      break
+    } catch (cause) {
+      if ((cause as NodeJS.ErrnoException).code !== "EEXIST") break
+    }
+    try {
+      if (Date.now() - statSync(lock).mtimeMs > WRITE_LOCK_STALE_MS) {
+        unlinkSync(lock)
+        continue
+      }
+    } catch {
+      continue // released meanwhile
+    }
+    if (Date.now() >= deadline) {
+      console.error("[hub] the Concierge session lock file stayed busy: writing without it")
+      break
+    }
+    pause(2 + Math.floor(Math.random() * 5))
+  }
+  try {
+    write()
+  } finally {
+    if (held) {
+      try {
+        unlinkSync(lock)
+      } catch {
+        // already gone
+      }
+    }
+  }
 }
 
 export class SessionContexts {
@@ -60,46 +116,62 @@ export class SessionContexts {
     this.locks = new Set(this.load())
   }
 
+  /** Every lock file read: the written one first, then the read-only ones. */
+  private files(): string[] {
+    return [...(this.options.lockFile ? [this.options.lockFile] : []), ...(this.options.readLockFiles ?? [])]
+  }
+
   /** Adds the locks another process wrote since the last read (locks are never removed). */
   private refresh(): void {
-    const file = this.options.lockFile
-    if (!file) return
-    let stamp: string
-    try {
-      stamp = stampOf(file)
-    } catch {
-      return
-    }
+    const files = this.files()
+    if (!files.length) return
+    const stamp = files
+      .map((file) => {
+        try {
+          return stampOf(file)
+        } catch {
+          return "-"
+        }
+      })
+      .join("|")
     if (stamp === this.lockStamp) return
     this.lockStamp = stamp
     for (const id of this.load()) this.locks.add(id)
   }
 
+  /** The union of the lock files' sessions (a missing or corrupt file adds none). */
   private load(): string[] {
-    if (!this.options.lockFile) return []
-    try {
-      const raw = JSON.parse(readFileSync(this.options.lockFile, "utf8")) as { v?: unknown; sessions?: unknown }
-      return raw.v === 1 && Array.isArray(raw.sessions) ? raw.sessions.filter((id): id is string => typeof id === "string" && id.length > 0 && id.length <= 200) : []
-    } catch {
-      return []
-    }
+    return this.files().flatMap((file) => {
+      try {
+        const raw = JSON.parse(readFileSync(file, "utf8")) as { v?: unknown; sessions?: unknown }
+        return raw.v === 1 && Array.isArray(raw.sessions) ? raw.sessions.filter((id): id is string => typeof id === "string" && id.length > 0 && id.length <= 200) : []
+      } catch {
+        return []
+      }
+    })
   }
 
   private lock(sessionID: string): void {
     this.refresh()
     if (this.locks.has(sessionID)) return
-    // Merge with what other processes wrote: never drop their locks.
-    for (const id of this.load()) this.locks.add(id)
     this.locks.add(sessionID)
-    while (this.locks.size > LOCKS_MAX) this.locks.delete(this.locks.values().next().value as string)
     const file = this.options.lockFile
-    if (!file) return
+    if (!file) return this.boundLocks()
     try {
       mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 })
-      const tmp = `${file}.${process.pid}.tmp`
-      writeFileSync(tmp, `${JSON.stringify({ v: 1, sessions: [...this.locks] })}\n`, { mode: 0o600 })
-      renameSync(tmp, file)
-      this.lockStamp = stampOf(file)
+      underWriteLock(file, this.options.lockWaitMs ?? WRITE_LOCK_WAIT_MS, () => {
+        // Merge with what other processes wrote (read under the write lock): never drop their locks.
+        for (const id of this.load()) this.locks.add(id)
+        // The newest lock last, so the bound never drops it.
+        this.locks.delete(sessionID)
+        this.locks.add(sessionID)
+        this.boundLocks()
+        const tmp = `${file}.${process.pid}.tmp`
+        writeFileSync(tmp, `${JSON.stringify({ v: 1, sessions: [...this.locks] })}\n`, { mode: 0o600 })
+        renameSync(tmp, file)
+      })
+      this.lockStamp = ""
+      this.refresh()
     } catch (cause) {
       // The lock still holds in this process; the hub re-sends the context after a restart.
       console.error(`[hub] could not persist the Concierge session lock: ${(cause as Error).message}`)
@@ -126,6 +198,11 @@ export class SessionContexts {
     return { revision: req.revision }
   }
 
+  /** At most LOCKS_MAX locks (the oldest dropped). */
+  private boundLocks(): void {
+    while (this.locks.size > LOCKS_MAX) this.locks.delete(this.locks.values().next().value as string)
+  }
+
   private bound(map: Map<string, unknown>): void {
     while (map.size > this.maxSessions) map.delete(map.keys().next().value as string)
   }
@@ -166,11 +243,14 @@ export class SessionContexts {
     return true
   }
 
-  /** What the sessions frame says about the session (locked ones only): its agent and context revision. */
-  report(sessionID: string): { agent?: string; contextRevision?: number } {
+  /**
+   * What the sessions frame says about the session (locked ones only): locked (FX-07: from the very first frame, even
+   * after a restart, before its agent is read or the hub re-sends a context), its agent and context revision.
+   */
+  report(sessionID: string): { locked?: true; agent?: string; contextRevision?: number } {
     if (!this.locks.has(sessionID)) return {}
     const agent = this.agents.get(sessionID)
     const revision = this.contexts.get(sessionID)?.revision
-    return { ...(agent ? { agent } : {}), ...(revision !== undefined ? { contextRevision: revision } : {}) }
+    return { locked: true, ...(agent ? { agent } : {}), ...(revision !== undefined ? { contextRevision: revision } : {}) }
   }
 }

package/src/spoke/spoke.ts

@@ -147,13 +147,14 @@ export interface SpokeHost {
    * only those of the locations it loaded. Absent (a TUI's own server, which this process cannot reach): the
    * process reports only the sessions it sees active.
    */
-  listRecent?(options?: { days: number; max: number; include: readonly string[] }): Promise<Array<{ id: string } & SessionDetails>>
+  /** `signal` aborts when the spoke abandons the listing because it timed out (listingTimeoutMs): stop asking the server. */
+  listRecent?(options?: { days: number; max: number; include: readonly string[]; signal?: AbortSignal }): Promise<Array<{ id: string } & SessionDetails>>
   /** Creates a session in a directory (service processes only). */
   createSession?(input: { directory: string; title?: string }): Promise<{ id: string }>
   /** MCP servers and their status for a directory (raw OpenCode McpServer list). */
   mcpList?(directory: string): Promise<ReadonlyArray<unknown>>
-  /** Working-tree changes of a directory (raw OpenCode FileDiffInfo list). */
-  vcsDiff?(directory: string): Promise<ReadonlyArray<unknown>>
+  /** Working-tree changes of a directory (raw OpenCode FileDiffInfo list); undefined when nothing can read that directory. */
+  vcsDiff?(directory: string): Promise<ReadonlyArray<unknown> | undefined>
   /** Current branch of a directory. */
   vcsBranch?(directory: string): Promise<string | undefined>
   /** (HWA-16) A location's local skill and command names (they win over a hub profile's); absent: none applied. */
@@ -187,6 +188,8 @@ const ANSWER_IN_TERMINAL = "This OpenCode process cannot answer questions from t
 export interface SpokeOptions {
   /** (CON-04) Where Concierge session locks persist (the plugin's state dir); memory only without it. */
   readonly conciergeLockFile?: string
+  /** Other Concierge lock files read, never written (the other default state dir places; FX-08, fail closed). */
+  readonly conciergeLockReadFiles?: readonly string[]
   readonly configFile: string
   readonly machineName: string
   readonly kind: ProcessKind
@@ -410,7 +413,10 @@ export class Spoke {
   ) {
     this.config = options.launch ? launchVoiceConfig(options.launch, options.machineName) : readConfig(options.configFile, options.machineName)
     this.hub = { pending: false, nextAt: 0, cooldown: options.localHubRetryMs ?? 30_000 }
-    this.contexts = new SessionContexts(options.conciergeLockFile ? { lockFile: options.conciergeLockFile } : {})
+    this.contexts = new SessionContexts({
+      ...(options.conciergeLockFile ? { lockFile: options.conciergeLockFile } : {}),
+      ...(options.conciergeLockReadFiles?.length ? { readLockFiles: options.conciergeLockReadFiles } : {}),
+    })
     const localNames = host.localNames?.bind(host)
     this.profiles = new OpenCodeProfiles({
       isBusy: (id) => this.running.has(id) || this.tracker.isBusy(id),
@@ -1824,13 +1830,15 @@ export class Spoke {
     const limit = this.options.listingTimeoutMs ?? LISTING_TIMEOUT_MS
     let timer: ReturnType<typeof setTimeout> | undefined
     const timedOut = Symbol("timeout")
+    const cancel = new AbortController()
     try {
       const keep = this.keep()
       const { days, max } = this.config.list
-      const listed = Promise.resolve(this.host.listRecent?.({ days, max, include: [...keep] }))
+      const listed = Promise.resolve(this.host.listRecent?.({ days, max, include: [...keep], signal: cancel.signal }))
       listed.catch(() => {}) // an abandoned listing that fails later is not an unhandled rejection
       const result = await Promise.race([listed, new Promise<typeof timedOut>((resolve) => (timer = setTimeout(() => resolve(timedOut), limit)))])
       if (result === timedOut) {
+        cancel.abort(new Error(`listing timed out after ${limit} ms`))
         if (!this.listingHung) console.error(`[hub] listing recent sessions timed out after ${limit} ms; listing again later`)
         this.listingHung = true
         return

package/web/dist/assets/ArtifactPage-mNzjlP_U.js

@@ -0,0 +1 @@
+import{At as e,Et as t,ft as n,i as r,r as i,yt as a}from"./ui-Dh1-78Cl.js";import{L as o,R as s,z as c}from"./index-lIOfSYck.js";import{t as l}from"./ArtifactWorkbench-NoFC5Sb2.js";var u=a(`<div class="feature-page av-page">`),d=a(`<a class="icon-btn av-back"href=/artifacts aria-label="All artifacts"title="All artifacts">`);function f(a){return(()=>{var f=u();return n(f,e(l,{get id(){return a.id},layout:`page`,get lead(){return[e(t,{get when(){return o()},get children(){return e(r,{icon:`menu`,label:`Open sidebar`,onClick:s})}}),(()=>{var t=d();return n(t,e(i,{name:`back`})),t})()]},get actions(){return e(r,{class:`av-wide`,icon:`split`,label:`Open in pane`,onClick:()=>c(a.id)})}})),f})()}export{f as default};

package/web/dist/assets/ArtifactPane-CPQcuX7c.js

@@ -0,0 +1 @@
+import{At as e,Pt as t,ft as n,ht as r,r as i,yt as a}from"./ui-Dh1-78Cl.js";import{t as o}from"./ArtifactWorkbench-NoFC5Sb2.js";var s=a(`<a class=icon-btn aria-label="Full page"title="Open the artifact's full page">`);function c(a){return e(o,{get id(){return a.artifactID},layout:`pane`,onArtifact:e=>a.onTitle?.(e.title||`Untitled`),get actions(){return(()=>{var o=s();return n(o,e(i,{name:`expand`})),t(()=>r(o,`href`,`/artifacts/${encodeURIComponent(a.artifactID)}`)),o})()},get trailing(){return a.paneTools}})}export{c as ArtifactPane};