@getfamiliar/shared 0.1.12 → 0.1.13

package/build/AgentRun.d.ts

@@ -40,18 +40,19 @@ export interface AgentRunRow {
      */
     readonly parentAgentrunId: string | null;
     /**
-     * Topic copied from the originating event at queue time. Combined
-     * with {@link handler} to resolve a workspace markdown file.
+     * The handler's address. Root agentruns copy the event's topic;
+     * spawned children carry the topic the spawning tool named. For
+     * topic `chat:whatsapp` the handler file is
+     * `workspace/chat/whatsapp.md` (or `workspace/chat/whatsapp/index.md`).
      */
     readonly topic: string;
     /**
-     * Basename of the handler file in the workspace (e.g. `index`,
-     * `analyze`). Resolution rules — for topic `chat:whatsapp` and
-     * handler `analyze`:
-     *   1. `workspace/chat/whatsapp/analyze.md`
-     *   2. fallback `workspace/chat/analyze.md`
+     * `true` when the topic must resolve to its own handler file;
+     * `false` when resolution may fall back up the topic chain
+     * (`chat:whatsapp` → `chat`). Root agentruns copy the event's
+     * {@link EventRow.isExactTopic}; spawned children are always exact.
      */
-    readonly handler: string;
+    readonly isExactTopic: boolean;
     /**
      * Resolved model id actually used for this run, of the form
      * `<provider>/<modelId>` (e.g. `featherless/zai-org/GLM-5.1`).
@@ -147,10 +148,14 @@ export interface NewAgentRun {
     readonly eventId: string;
     /** FK to the parent agentrun, or omitted/null for the root agentrun. */
     readonly parentAgentrunId?: string | null;
-    /** Topic copied from the event. Required. */
+    /** Handler address — the event's topic for roots, the named topic for children. Required. */
     readonly topic: string;
-    /** Handler basename (e.g. `index`). Required. */
-    readonly handler: string;
+    /**
+     * Whether handler resolution must match the topic exactly. Default
+     * `true` (the column default) — only the input-event watcher passes
+     * `false`, for events whose topic may fall back up the chain.
+     */
+    readonly isExactTopic?: boolean;
     /** Defaults to 50; usually inherited from the event. */
     readonly priority?: number;
     /** Initial state; default `"pending"`. */

package/build/AgentRunBus.js

@@ -44,13 +44,13 @@ export class AgentRunBus {
      */
     async add(run) {
         const result = await this.connection.getPool().query(`INSERT INTO agentruns
-                (event_id, parent_agentrun_id, topic, handler, priority, state, prompt, payload, privileged, calltype)
+                (event_id, parent_agentrun_id, topic, is_exact_topic, priority, state, prompt, payload, privileged, calltype)
              VALUES ($1, $2, $3, $4, $5, $6, $7, $8::jsonb, $9, $10)
              RETURNING *`, [
             run.eventId,
             run.parentAgentrunId ?? null,
             run.topic,
-            run.handler,
+            run.isExactTopic ?? true,
             run.priority ?? 50,
             run.state ?? "pending",
             run.prompt ?? null,
@@ -339,7 +339,7 @@ function mapRow(raw) {
         eventId: raw.event_id,
         parentAgentrunId: raw.parent_agentrun_id,
         topic: raw.topic,
-        handler: raw.handler,
+        isExactTopic: raw.is_exact_topic,
         priority: raw.priority,
         state: raw.state,
         prompt: raw.prompt,

package/build/Config.d.ts

@@ -19,6 +19,11 @@
  * boot. Plugin-side keys are not policed by the platform — plugins own
  * the validation of their own subtrees.
  */
+/**
+ * Fallback for `core.writablePaths` when `config.yml` doesn't set it:
+ * the workspace globs the agent may write to, which are never handlers.
+ */
+export declare const DEFAULT_WRITABLE_PATHS: readonly string[];
 export interface ConfigService {
     /**
      * Read a string under a dotted path. Throws when the key is

package/build/Config.js

@@ -1 +1,26 @@
-export {};
+/**
+ * Plugin-agnostic configuration surface exposed by the host.
+ *
+ * Plugins reach configuration through `HostContext.config` rather than
+ * touching `process.env` or reading the YAML file themselves. The
+ * service intentionally has no plugin-specific types; everything is
+ * keyed by dotted path strings (e.g. `"core.postgresPassword"`,
+ * `"telegram.botToken"`) and validated to a primitive shape at the
+ * call site.
+ *
+ * Required-vs-optional semantics live in the call signature, not in
+ * the schema: omitting `defaultValue` makes the read throw on missing
+ * or wrong-shaped data, while supplying one widens the return type to
+ * include the default (so plugins can pass `null` for fields they
+ * tolerate being absent).
+ *
+ * The platform-level minimum (the keys without which the daemon can't
+ * start) is enforced by a separate `ConfigLinter` on the host side at
+ * boot. Plugin-side keys are not policed by the platform — plugins own
+ * the validation of their own subtrees.
+ */
+/**
+ * Fallback for `core.writablePaths` when `config.yml` doesn't set it:
+ * the workspace globs the agent may write to, which are never handlers.
+ */
+export const DEFAULT_WRITABLE_PATHS = ["wiki/**", "files/**"];

package/build/Event.d.ts

@@ -41,9 +41,9 @@ export interface EventRow {
      */
     readonly id: string;
     /**
-     * Event topic, matching `\w+(:\w+)*` (e.g. `mail`, `chat:whatsapp`,
-     * `chat:telegram:group:reaction`). Each `:`-separated segment maps
-     * to a folder when the container resolves the handler markdown.
+     * Event topic, matching `TOPIC_PATTERN` (e.g. `mail`, `chat:whatsapp`,
+     * `chat:telegram:group:reaction`). The topic is the handler's whole
+     * address: `a:b:c` resolves to `a/b/c.md` (or `a/b/c/index.md`).
      */
     readonly topic: string;
     /**
@@ -94,12 +94,12 @@ export interface EventRow {
      */
     readonly prompt: string;
     /**
-     * Override for the root agentrun's handler. `null` means the
-     * input-event watcher uses `'index'` (i.e. resolves
-     * `<topic>/index.md`). Set by the emitter via
-     * {@link NewEvent.startHandler}; never mutated after insert.
+     * `true` when the topic must name an existing handler file exactly;
+     * `false` when handler resolution may fall back up the topic chain.
+     * Set by the emitter via {@link NewEvent.isExactTopic}; never
+     * mutated after insert.
      */
-    readonly startHandler: string | null;
+    readonly isExactTopic: boolean;
     /**
      * `true` when this event was emitted by a trusted user-input source
      * (the operator at the local terminal via cli-chat, the operator on
@@ -236,24 +236,24 @@ export interface NewEvent {
      *
      * Use this for plugin emitters that want a chatmessage text
      * different from `prompt` (e.g. cli-chat persists the slash-
-     * prefixed `/topic/handler …` line while the handler sees only
+     * prefixed `/topic/sub …` line while the handler sees only
      * the trailing prompt text). When unset and `isChat: true`, the
      * existing path inserts `prompt` itself.
      */
     readonly userChatMessage?: string;
     /**
-     * Override which handler markdown the root agentrun runs. When
-     * omitted, the input-event watcher uses `'index'` (i.e. resolves
-     * `<topic>/index.md`). Useful when an emitter wants to skip the
-     * triage `index.md` and invoke a specific handler directly.
+     * When `true`, the topic addresses one handler file exactly
+     * (`a:b:c` → `a/b/c.md` or `a/b/c/index.md`) and the run fails if
+     * it is missing. Default `false`: world events fall back up the
+     * topic chain (`a:b`, then `a`) to the most specific existing
+     * handler. Set it for emissions that name a handler rather than
+     * report a world change — cron firings, scheduled wake-ups,
+     * memory's `skills:memory:save`, cli-chat slash commands.
      *
-     * Pass the basename without `.md` (e.g. `'analyze'` resolves to
-     * `<topic>/analyze.md`). The agentrun fails loud at handler-load
-     * time if no such file exists — there is no shape validation
-     * here, mirroring how `topic` is only regex-checked, not
-     * existence-checked, at emit time.
+     * Like `topic` itself, existence is not checked at emit time; the
+     * agentrun fails loud at handler-load time.
      */
-    readonly startHandler?: string;
+    readonly isExactTopic?: boolean;
     /**
      * Auxiliary files to stage at `/scratch/<event-id>/<name>` for this
      * event. Visible to the agent and to every MCP container under the

package/build/EventBus.d.ts

@@ -116,7 +116,7 @@ export declare class EventBus {
      */
     listLatest(limit: number): Promise<EventRow[]>;
     /**
-     * Fetch the most recently created N event rows whose topic, start_handler,
+     * Fetch the most recently created N event rows whose topic,
      * prompt, or payload (cast to text) case-insensitively contains `needle`.
      * Used by `familiar events list <search>` so the operator can grep the
      * recent bus without piping through `grep`.
@@ -138,7 +138,7 @@ export declare class EventBus {
      * pair can't express. Both of those stay as the CLI's call sites.
      *
      * Substring match (when `search` is set) is the same ILIKE-against-
-     * `(topic, start_handler, prompt, payload::text)` predicate
+     * `(topic, prompt, payload::text)` predicate
      * {@link searchLatest} uses. `dateFrom` is inclusive, `dateTo` is
      * exclusive (`created_at >= $from AND created_at < $to`), so the
      * agent can pass two midnights to get a single local day without

package/build/EventBus.js

@@ -139,7 +139,7 @@ export class EventBus {
             const result = await client.query(`INSERT INTO events
                    (topic, payload, priority, state, idempotency_key,
                     is_chat, preferred_chat_channel_id, prompt, privileged,
-                    start_handler, output_chat_on_failure)
+                    is_exact_topic, output_chat_on_failure)
                  VALUES ($1, $2::jsonb, $3, $4, $5, $6, $7, $8, $9, $10, $11)
                  RETURNING *`, [
                 event.topic,
@@ -151,7 +151,7 @@ export class EventBus {
                 event.preferredChatChannelId ?? null,
                 prompt,
                 event.privileged ?? false,
-                event.startHandler ?? null,
+                event.isExactTopic ?? false,
                 event.outputChatOnFailure ?? false,
             ]);
             const row = mapRow(result.rows[0]);
@@ -242,7 +242,7 @@ export class EventBus {
         return result.rows.map(mapRow);
     }
     /**
-     * Fetch the most recently created N event rows whose topic, start_handler,
+     * Fetch the most recently created N event rows whose topic,
      * prompt, or payload (cast to text) case-insensitively contains `needle`.
      * Used by `familiar events list <search>` so the operator can grep the
      * recent bus without piping through `grep`.
@@ -259,7 +259,6 @@ export class EventBus {
         const pattern = `%${needle.replace(/[\\%_]/g, (c) => `\\${c}`)}%`;
         const result = await this.connection.getPool().query(`SELECT * FROM events
                  WHERE topic                          ILIKE $2
-                    OR coalesce(start_handler, '')    ILIKE $2
                     OR coalesce(prompt, '')           ILIKE $2
                     OR payload::text                  ILIKE $2
                  ORDER BY created_at DESC, id DESC
@@ -274,7 +273,7 @@ export class EventBus {
      * pair can't express. Both of those stay as the CLI's call sites.
      *
      * Substring match (when `search` is set) is the same ILIKE-against-
-     * `(topic, start_handler, prompt, payload::text)` predicate
+     * `(topic, prompt, payload::text)` predicate
      * {@link searchLatest} uses. `dateFrom` is inclusive, `dateTo` is
      * exclusive (`created_at >= $from AND created_at < $to`), so the
      * agent can pass two midnights to get a single local day without
@@ -286,8 +285,7 @@ export class EventBus {
         let n = 1;
         if (filter.search !== undefined && filter.search.length > 0) {
             const pattern = `%${filter.search.replace(/[\\%_]/g, (c) => `\\${c}`)}%`;
-            conditions.push(`(topic ILIKE $${n} OR coalesce(start_handler, '') ILIKE $${n} ` +
-                `OR coalesce(prompt, '') ILIKE $${n} OR payload::text ILIKE $${n})`);
+            conditions.push(`(topic ILIKE $${n} OR coalesce(prompt, '') ILIKE $${n} OR payload::text ILIKE $${n})`);
             values.push(pattern);
             n++;
         }
@@ -473,7 +471,7 @@ function mapRow(raw) {
         isChat: raw.is_chat,
         preferredChatChannelId: raw.preferred_chat_channel_id,
         prompt: raw.prompt ?? "",
-        startHandler: raw.start_handler,
+        isExactTopic: raw.is_exact_topic,
         privileged: raw.privileged,
         outputChatOnFailure: raw.output_chat_on_failure,
         createdAt: raw.created_at,

package/build/HandlerCatalog.d.ts

@@ -1,31 +1,35 @@
+import { type HandlerResolution, type HandlerResolutionOptions } from "./HandlerResolution.js";
 /**
  * One handler entry surfaced by {@link HandlerCatalog.list}.
  *
- * Encodes the same notion as the container's `HandlerFile`: a topic
- * (one or more `:`-separated segments) plus a basename. `slashPath`
- * is the user-facing form the cli-chat prompt accepts as a direct
- * handler call (e.g. `/grocery/fruits/order`).
+ * The topic is the handler's whole address (`chat:telegram` for both
+ * `chat/telegram.md` and `chat/telegram/index.md`). `slashPath` is the
+ * user-facing form the cli-chat prompt accepts as a direct handler call
+ * (e.g. `/grocery/fruits/order`).
  */
 export interface HandlerPath {
     /** Colon-separated topic, e.g. `chat:telegram`. */
     readonly topic: string;
-    /** Handler basename without `.md`, e.g. `index`, `analyze`. */
-    readonly handler: string;
     /** Absolute path on disk of the handler file. */
     readonly absolutePath: string;
-    /** Workspace-relative posix path, e.g. `chat/telegram/index.md`. */
+    /** Workspace-relative posix path, e.g. `chat/telegram.md`. */
     readonly relativePath: string;
-    /** User-facing slash form, e.g. `/chat/telegram/index`. */
+    /** User-facing slash form of the topic, e.g. `/chat/telegram`. */
     readonly slashPath: string;
 }
+/** A {@link HandlerResolution} plus the winning file's absolute path. */
+export interface ResolvedHandler extends HandlerResolution {
+    /** Absolute path on disk of the winning handler file. */
+    readonly absolutePath: string;
+}
 /**
  * Read-only view over the `workspace/` directory's handler files.
  *
- * Mirrors the resolution semantics implemented by
- * `container/src/HandlerFile.ts` so host-side code (CLI, cron
+ * Shares the resolution rules of `container/src/HandlerFile.ts` (both
+ * build on `HandlerResolution.ts`) so host-side code (CLI, cron
  * scheduler introspection, tab-completion) can answer "does this
  * handler exist?" and "list every handler" without depending on
- * container internals or reimplementing the topic-walk inheritance.
+ * container internals.
  *
  * The catalog is stateless on the disk — every method re-scans —
  * so live workspace edits are reflected without a daemon restart.
@@ -46,12 +50,14 @@ export declare class HandlerCatalog {
     constructor(workspaceDir: string, writablePathGlobs?: readonly string[]);
     /**
      * Walk `workspace/` and return one {@link HandlerPath} per
-     * candidate handler file. Excludes every file at the workspace root
-     * (`PROMPT.md`, `SOUL.md`, … — root files have no topic, so they are
-     * never handlers) and the `skills/` subtree. Every other `.md` file under a topic
-     * directory is included, even if it's a knowledge file (e.g.
-     * `people/anna.md`) — `HandlerCatalog` does not police what is or
-     * isn't a "proper" handler; that's a handler-loading concern.
+     * addressable handler file. Excludes every file at the workspace
+     * root (`PROMPT.md`, `SOUL.md`, … — root files have no topic, so they
+     * are never handlers), the `skills/` subtree, writable paths, file
+     * names that don't form a valid topic, and a folder-form
+     * `x/index.md` shadowed by its `x.md` twin. Every other `.md` file
+     * under a topic directory is included, even if it's a knowledge file
+     * (e.g. `people/anna.md`) — `HandlerCatalog` does not police what is
+     * or isn't a "proper" handler; that's a handler-loading concern.
      *
      * Sorted by `slashPath` for stable display ordering in
      * tab-completion. Returns an empty array when the workspace
@@ -59,17 +65,16 @@ export declare class HandlerCatalog {
      */
     list(): Promise<readonly HandlerPath[]>;
     /**
-     * Resolve a handler call: given a topic (e.g. `chat:telegram`)
-     * and a basename (e.g. `index`), return the absolute path of the
-     * deepest existing handler file, mirroring the container's
-     * inheritance walk.
+     * Resolve a topic to the one handler file that runs for it, with
+     * the same rules as the container's `HandlerFile.load`: file form
+     * `a/b/c.md` before folder form `a/b/c/index.md`, and — unless
+     * `isExactTopic` — falling back up the topic chain.
      *
-     * For topic `a:b:c` and basename `x` the resolution tries, in
-     * order: `a/b/c/x.md`, `a/b/x.md`, `a/x.md`. Returns the first
-     * existing path or `null` if none exist. The deepest existing
-     * file is what `HandlerFile.load` would treat as the leaf — for
-     * cli-chat existence checks, that's exactly the question we
-     * want answered.
+     * @param topic Colon-separated topic, e.g. `chat:telegram`.
+     * @param options See {@link HandlerResolutionOptions}.
+     * @returns The resolution, or `null` when nothing matches or the
+     *   winning file lives under a writable path (the container refuses
+     *   to run it, so it does not resolve).
      */
-    resolve(topic: string, handler: string): Promise<string | null>;
+    resolve(topic: string, options: HandlerResolutionOptions): Promise<ResolvedHandler | null>;
 }

package/build/HandlerCatalog.js

@@ -1,5 +1,6 @@
-import { promises as fs } from "node:fs";
+import { promises as fs, statSync } from "node:fs";
 import path from "node:path";
+import { resolveHandlerPath, topicFromHandlerPath, twinHandlerPath, } from "./HandlerResolution.js";
 import { matchesAnyGlob } from "./PathGlob.js";
 /**
  * Workspace subtrees excluded from {@link HandlerCatalog.list} (cli-chat
@@ -13,11 +14,11 @@ const RESERVED_TOP_DIRS = new Set(["skills"]);
 /**
  * Read-only view over the `workspace/` directory's handler files.
  *
- * Mirrors the resolution semantics implemented by
- * `container/src/HandlerFile.ts` so host-side code (CLI, cron
+ * Shares the resolution rules of `container/src/HandlerFile.ts` (both
+ * build on `HandlerResolution.ts`) so host-side code (CLI, cron
  * scheduler introspection, tab-completion) can answer "does this
  * handler exist?" and "list every handler" without depending on
- * container internals or reimplementing the topic-walk inheritance.
+ * container internals.
  *
  * The catalog is stateless on the disk — every method re-scans —
  * so live workspace edits are reflected without a daemon restart.
@@ -41,12 +42,14 @@ export class HandlerCatalog {
     }
     /**
      * Walk `workspace/` and return one {@link HandlerPath} per
-     * candidate handler file. Excludes every file at the workspace root
-     * (`PROMPT.md`, `SOUL.md`, … — root files have no topic, so they are
-     * never handlers) and the `skills/` subtree. Every other `.md` file under a topic
-     * directory is included, even if it's a knowledge file (e.g.
-     * `people/anna.md`) — `HandlerCatalog` does not police what is or
-     * isn't a "proper" handler; that's a handler-loading concern.
+     * addressable handler file. Excludes every file at the workspace
+     * root (`PROMPT.md`, `SOUL.md`, … — root files have no topic, so they
+     * are never handlers), the `skills/` subtree, writable paths, file
+     * names that don't form a valid topic, and a folder-form
+     * `x/index.md` shadowed by its `x.md` twin. Every other `.md` file
+     * under a topic directory is included, even if it's a knowledge file
+     * (e.g. `people/anna.md`) — `HandlerCatalog` does not police what is
+     * or isn't a "proper" handler; that's a handler-loading concern.
      *
      * Sorted by `slashPath` for stable display ordering in
      * tab-completion. Returns an empty array when the workspace
@@ -57,50 +60,66 @@ export class HandlerCatalog {
         if (!exists) {
             return [];
         }
+        const relativePaths = [];
+        await walkMarkdown(this.workspaceDir, [], relativePaths);
+        const present = new Set(relativePaths);
         const results = [];
-        await walkMarkdown(this.workspaceDir, [], results, this.workspaceDir, this.writablePathGlobs);
+        for (const relativePath of relativePaths) {
+            // Files under `core.writablePaths` (e.g. `wiki/**`) are writable by
+            // non-privileged runs and are never handlers — never propose them.
+            if (matchesAnyGlob(this.writablePathGlobs, relativePath)) {
+                continue;
+            }
+            const topic = topicFromHandlerPath(relativePath);
+            if (topic === null) {
+                continue;
+            }
+            const twin = twinHandlerPath(relativePath);
+            if (relativePath.endsWith("/index.md") && twin !== null && present.has(twin)) {
+                continue;
+            }
+            results.push({
+                topic,
+                absolutePath: path.join(this.workspaceDir, relativePath),
+                relativePath,
+                slashPath: `/${topic.split(":").join("/")}`,
+            });
+        }
         results.sort((a, b) => a.slashPath.localeCompare(b.slashPath));
         return results;
     }
     /**
-     * Resolve a handler call: given a topic (e.g. `chat:telegram`)
-     * and a basename (e.g. `index`), return the absolute path of the
-     * deepest existing handler file, mirroring the container's
-     * inheritance walk.
+     * Resolve a topic to the one handler file that runs for it, with
+     * the same rules as the container's `HandlerFile.load`: file form
+     * `a/b/c.md` before folder form `a/b/c/index.md`, and — unless
+     * `isExactTopic` — falling back up the topic chain.
      *
-     * For topic `a:b:c` and basename `x` the resolution tries, in
-     * order: `a/b/c/x.md`, `a/b/x.md`, `a/x.md`. Returns the first
-     * existing path or `null` if none exist. The deepest existing
-     * file is what `HandlerFile.load` would treat as the leaf — for
-     * cli-chat existence checks, that's exactly the question we
-     * want answered.
+     * @param topic Colon-separated topic, e.g. `chat:telegram`.
+     * @param options See {@link HandlerResolutionOptions}.
+     * @returns The resolution, or `null` when nothing matches or the
+     *   winning file lives under a writable path (the container refuses
+     *   to run it, so it does not resolve).
      */
-    async resolve(topic, handler) {
-        const segments = topic.split(":");
-        for (let depth = segments.length; depth >= 1; depth--) {
-            const rel = path.join(...segments.slice(0, depth), `${handler}.md`);
-            const relPosix = rel.split(path.sep).join("/");
-            const absolute = path.join(this.workspaceDir, rel);
-            if (await fileExists(absolute)) {
-                // A file under `core.writablePaths` is never a handler, even
-                // when it exists — mirror the container's `HandlerFile.load`
-                // guard so host-side callers agree it does not resolve.
-                if (matchesAnyGlob(this.writablePathGlobs, relPosix)) {
-                    return null;
-                }
-                return absolute;
-            }
+    async resolve(topic, options) {
+        const resolution = resolveHandlerPath(topic, options, (relativePath) => isFileSync(path.join(this.workspaceDir, relativePath)));
+        if (resolution === null ||
+            matchesAnyGlob(this.writablePathGlobs, resolution.relativePath)) {
+            return null;
         }
-        return null;
+        return {
+            ...resolution,
+            absolutePath: path.join(this.workspaceDir, resolution.relativePath),
+        };
     }
 }
 /**
- * Recursively walk `dir`, accumulating one {@link HandlerPath} per
- * `.md` file. `segments` tracks the topic path from the workspace
- * root; an empty array means we're at the root, whose files are
- * skipped (no topic, never a handler).
+ * Recursively walk `dir`, accumulating the workspace-relative posix
+ * path of every `.md` file below a topic folder. `segments` tracks the
+ * folder path from the workspace root; files at the root itself are
+ * skipped (no topic, never a handler), and so is the reserved
+ * `skills/` subtree.
  */
-async function walkMarkdown(dir, segments, out, workspaceDir, writablePathGlobs) {
+async function walkMarkdown(dir, segments, out) {
     let entries;
     try {
         entries = await fs.readdir(dir, { withFileTypes: true });
@@ -113,35 +132,22 @@ async function walkMarkdown(dir, segments, out, workspaceDir, writablePathGlobs)
             if (segments.length === 0 && RESERVED_TOP_DIRS.has(entry.name)) {
                 continue;
             }
-            await walkMarkdown(path.join(dir, entry.name), [...segments, entry.name], out, workspaceDir, writablePathGlobs);
+            await walkMarkdown(path.join(dir, entry.name), [...segments, entry.name], out);
             continue;
         }
-        if (!entry.isFile() || !entry.name.endsWith(".md")) {
+        if (!entry.isFile() || !entry.name.endsWith(".md") || segments.length === 0) {
             continue;
         }
-        if (segments.length === 0) {
-            // `.md` at the workspace root (PROMPT.md, SOUL.md, …) has no
-            // topic folder — never a handler. Skip silently rather than
-            // reporting an empty topic.
-            continue;
-        }
-        const handlerBase = entry.name.slice(0, -".md".length);
-        const topic = segments.join(":");
-        const absolutePath = path.join(dir, entry.name);
-        const relativePath = path.relative(workspaceDir, absolutePath).split(path.sep).join("/");
-        // Files under `core.writablePaths` (e.g. `wiki/**`) are writable by
-        // non-privileged runs and are never handlers — never propose them.
-        if (matchesAnyGlob(writablePathGlobs, relativePath)) {
-            continue;
-        }
-        const slashPath = `/${[...segments, handlerBase].join("/")}`;
-        out.push({ topic, handler: handlerBase, absolutePath, relativePath, slashPath });
+        out.push([...segments, entry.name].join("/"));
     }
 }
-async function fileExists(absolute) {
+/**
+ * Synchronous regular-file probe, used as the existence callback of
+ * {@link resolveHandlerPath}.
+ */
+function isFileSync(absolute) {
     try {
-        const stat = await fs.stat(absolute);
-        return stat.isFile();
+        return statSync(absolute).isFile();
     }
     catch {
         return false;

package/build/HandlerResolution.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Outcome of {@link resolveHandlerPath}: the one handler file a topic
+ * resolves to.
+ */
+export interface HandlerResolution {
+    /** Workspace-relative posix path of the winning file, e.g. `mail/new/ms365.md`. */
+    readonly relativePath: string;
+    /**
+     * Workspace-relative path of the twin that lost against
+     * {@link relativePath} on the same level (`mail/new/ms365/index.md`
+     * when `mail/new/ms365.md` also exists), or `null` when the level
+     * held only one file. Only one of the two forms is allowed; callers
+     * warn when this is set.
+     */
+    readonly shadowedPath: string | null;
+}
+/**
+ * Options for {@link handlerCandidateLevels} / {@link resolveHandlerPath}.
+ */
+export interface HandlerResolutionOptions {
+    /**
+     * `true` ⇒ only the topic's own level is tried (cron, subagents,
+     * scheduled wake-ups, addressed emissions). `false` ⇒ the resolver
+     * walks up the topic chain (`a:b:c → a:b → a`), which is what
+     * world events get.
+     */
+    readonly isExactTopic: boolean;
+}
+/**
+ * Build the candidate handler files for a topic, one entry per topic
+ * level (most specific first). Each level lists its candidates in
+ * precedence order: the file form `a/b/c.md` before the folder form
+ * `a/b/c/index.md`. A single-segment topic `a` has only `a/index.md`
+ * — workspace-root files are never handlers.
+ *
+ * For topic `mail:new:ms365` without `isExactTopic`:
+ *
+ *   1. `mail/new/ms365.md`, `mail/new/ms365/index.md`
+ *   2. `mail/new.md`, `mail/new/index.md`
+ *   3. `mail/index.md`
+ *
+ * @param topic Colon-separated topic, e.g. `mail:new:ms365`.
+ * @param options See {@link HandlerResolutionOptions}.
+ * @returns The candidate levels, most specific first.
+ */
+export declare function handlerCandidateLevels(topic: string, options: HandlerResolutionOptions): readonly (readonly string[])[];
+/**
+ * Resolve a topic to the single handler file that runs for it. The
+ * first level of {@link handlerCandidateLevels} holding any existing
+ * file wins; within a level the file form beats the folder form and
+ * the loser is reported as {@link HandlerResolution.shadowedPath}.
+ * Nothing is merged — exactly one file is the handler.
+ *
+ * @param topic Colon-separated topic, e.g. `mail:new:ms365`.
+ * @param options See {@link HandlerResolutionOptions}.
+ * @param isFile Existence probe for a workspace-relative path.
+ * @returns The resolution, or `null` when no candidate exists.
+ */
+export declare function resolveHandlerPath(topic: string, options: HandlerResolutionOptions, isFile: (relativePath: string) => boolean): HandlerResolution | null;
+/**
+ * Derive the topic a handler file answers to. The inverse of
+ * {@link handlerCandidateLevels}' own level:
+ *
+ * - `mail/important/digest.md` → `mail:important:digest`
+ * - `mail/new/index.md` → `mail:new`
+ * - `mail/index.md` → `mail`
+ *
+ * @param relativePath Workspace-relative posix path ending in `.md`.
+ * @returns The topic, or `null` for workspace-root files, non-`.md`
+ *   files and paths whose segments don't form a valid topic (e.g. a
+ *   file name containing a dot or a space).
+ */
+export declare function topicFromHandlerPath(relativePath: string): string | null;
+/**
+ * The other form of the same handler: `a/b/c.md` ↔ `a/b/c/index.md`.
+ * Only one of the two may exist; seeding and the cron scheduler use
+ * this to detect the conflict.
+ *
+ * @param relativePath Workspace-relative posix path ending in `.md`.
+ * @returns The twin's path, or `null` when the twin would be a
+ *   workspace-root file (`a/index.md` ↔ `a.md`) or the path is a root
+ *   file / not markdown.
+ */
+export declare function twinHandlerPath(relativePath: string): string | null;