privateer-agent 0.6.10 → 0.8.0

package/src/remote/remoteBridge.ts

@@ -27,6 +27,7 @@ export interface RelayLike {
   sendCommands(commands: { name: string; description?: string }[]): void;
   requestSelect(id: string, req: SelectRequest): void;
   requestInput(id: string, req: InputRequest): void;
+  sendFileMatches(id: string, matches: { path: string; isDir: boolean }[]): void;
   sendExtensions(payload: ExtensionsPayload): void;
   sendSkills(payload: SkillsPayload): void;
 }
@@ -93,6 +94,9 @@ export interface RemoteBridgeConfig {
   onSkillCreate?: (skill: { name: string; description: string; instructions: string }, sig?: string, ts?: number) => void;
   onSkillDelete?: (name: string, sig?: string, ts?: number) => void;
   onSkillSetEnabled?: (name: string, enabled: boolean, sig?: string, ts?: number) => void;
+  // The app is autocompleting an `@file` mention in its composer — the owner should
+  // list the cwd files matching `query` and reply via sendFileMatches(id, …).
+  onFilesSearch?: (id: string, query: string) => void;
   // A controller (re)attached — the owner should push a transcript snapshot.
   onControllerAttached?: () => void;
   onStatus?: (text: string) => void;
@@ -139,7 +143,7 @@ export class RemoteBridge {
     onSkillCreate: (skill, sig, ts) => this.cfg.onSkillCreate?.(skill, sig, ts),
     onSkillDelete: (name, sig, ts) => this.cfg.onSkillDelete?.(name, sig, ts),
     onSkillSetEnabled: (name, enabled, sig, ts) => this.cfg.onSkillSetEnabled?.(name, enabled, sig, ts),
-    // Routines are owned by the daemon, not an interactive session, so its own relay
+    // Routines are owned by the harbor, not an interactive session, so its own relay
     // (not this bridge) handles routines_*. These no-ops just satisfy Required — an
     // interactive terminal never surfaces the routines manager in the app.
     onRoutinesList: () => {},
@@ -147,25 +151,25 @@ export class RemoteBridge {
     onRoutinesDelete: () => {},
     onRoutinesSetEnabled: () => {},
     onRoutinesRun: () => {},
-    // Ad-hoc task spawns are daemon-owned too (they run on / are stood up by the daemon,
+    // Ad-hoc task spawns are harbor-owned too (they run on / are stood up by the harbor,
     // not an interactive session), so its own relay handles task_submit/task_spawn. These
     // no-ops just satisfy Required — an interactive terminal never receives them.
     onTaskSubmit: () => {},
     onTaskSpawn: () => {},
-    // Channels, like routines, are owned by the daemon (its channels/run.ts config),
-    // not an interactive session — the daemon's own relay handles channels_*. These
+    // Channels, like routines, are owned by the harbor (its channels/run.ts config),
+    // not an interactive session — the harbor's own relay handles channels_*. These
     // no-ops just satisfy Required; an interactive terminal never surfaces channels.
     onChannelsList: () => {},
     onChannelsSave: () => {},
     onChannelsRemove: () => {},
-    // MCP connectors, like channels, are managed on the daemon (the host that runs the
-    // adapter) — the daemon's own relay handles mcp_*. These no-ops just satisfy Required;
+    // MCP connectors, like channels, are managed on the harbor (the host that runs the
+    // adapter) — the harbor's own relay handles mcp_*. These no-ops just satisfy Required;
     // an interactive terminal manages MCP over IPC (desktop), never over this relay.
     onMcpList: () => {},
     onMcpSave: () => {},
     onMcpSetEnabled: () => {},
     onMcpRemove: () => {},
-    // Workflows, like routines/channels, are daemon-owned — the daemon's own relay handles
+    // Workflows, like routines/channels, are harbor-owned — the harbor's own relay handles
     // workflows_*. These no-ops just satisfy Required; an interactive terminal never
     // surfaces workflows.
     onWorkflowsList: () => {},
@@ -185,6 +189,7 @@ export class RemoteBridge {
       const resolve = this.pendingInputs.get(id);
       if (resolve) resolve(value);
     },
+    onFilesSearch: (id, query) => this.cfg.onFilesSearch?.(id, query),
     onNoQuarter: (on) => {
       this.noQuarter = on;
       this.relay?.sendNoQuarter(on); // echo the ack back so the app's toggle syncs
@@ -239,6 +244,11 @@ export class RemoteBridge {
     this.relay?.sendCommands(commands);
   }
 
+  // Reply to an app `@file` autocomplete query with the matching cwd entries.
+  sendFileMatches(id: string, matches: { path: string; isDir: boolean }[]): void {
+    this.relay?.sendFileMatches(id, matches);
+  }
+
   // Push the installed-extensions snapshot to the app's extensions manager.
   sendExtensions(payload: ExtensionsPayload): void {
     this.relay?.sendExtensions(payload);

package/src/remote/routinesControl.ts

@@ -2,15 +2,15 @@
  * Routine management for the app.
  *
  * A UI-agnostic wrapper over the routines store so the app (over the relay) can
- * see the daemon's saved routines and create / edit / delete / pause / run them —
+ * see the harbor's saved routines and create / edit / delete / pause / run them —
  * the sibling of extensionsControl.ts and skillsControl.ts, but for scheduled
  * tasks rather than Pi packages/skills.
  *
- * Unlike those two, routines are owned by the DAEMON (not an interactive Pi
+ * Unlike those two, routines are owned by the HARBOR (not an interactive Pi
  * session): they live in routines.json (see routines/store.ts) and fire from the
- * resident scheduler. So this control is wired into the daemon's own relay
+ * resident scheduler. So this control is wired into the harbor's own relay
  * connection (the "Privateer Routines" terminal), not the REPL/TUI. Running a
- * routine now is the one action that needs the daemon itself, so it's injected as
+ * routine now is the one action that needs the harbor itself, so it's injected as
  * `runNow` rather than reaching back into the store.
  *
  * Framework-agnostic: nothing here imports React or the relay. The caller owns the
@@ -75,7 +75,7 @@ export interface RoutinesControl {
   remove(idOrName: string): { ok: boolean; message?: string };
   // Pause/resume a routine. Resuming reschedules nextRun; pausing clears it.
   setEnabled(idOrName: string, enabled: boolean): { ok: boolean; message?: string };
-  // Run a routine now (fire-and-forget on the daemon). ok:false when not found.
+  // Run a routine now (fire-and-forget on the harbor). ok:false when not found.
   run(idOrName: string): { ok: boolean; message?: string };
 }
 
@@ -122,11 +122,11 @@ function toRemote(r: Routine): RemoteRoutine {
 }
 
 export function makeRoutinesControl(opts: {
-  // Working directory for a new routine when the draft omits `cwd` (the daemon's).
+  // Working directory for a new routine when the draft omits `cwd` (the harbor's).
   defaultCwd: () => string;
   // Is a webhook name declared in config? Guards "webhook:<name>" delivery entries.
   webhookExists?: (name: string) => boolean;
-  // Fire a routine now — injected by the daemon (its runRoutine). Absent → run is
+  // Fire a routine now — injected by the harbor (its runRoutine). Absent → run is
   // reported unavailable rather than silently dropped.
   runNow?: (routine: Routine) => void;
 }): RoutinesControl {

package/src/remote/workflowsControl.ts

@@ -3,12 +3,12 @@
  *
  * The sibling of routinesControl.ts / channelsControl.ts, for declarative workflow
  * graphs. UI-agnostic: nothing here imports React or the relay — the caller (the
- * daemon) owns the frame plumbing, the signed-frame gate (authorizeControl), and the
- * run seam. Like routines, workflows are owned by the DAEMON (they run on its resident
- * scheduler / on-demand), so this control is wired into the daemon's own relay.
+ * harbor) owns the frame plumbing, the signed-frame gate (authorizeControl), and the
+ * run seam. Like routines, workflows are owned by the HARBOR (they run on its resident
+ * scheduler / on-demand), so this control is wired into the harbor's own relay.
  *
  * A workflow file is an EXECUTABLE artifact (it can carry `script` steps), so the
- * daemon MUST verify the account signature on every mutating frame (workflows_save /
+ * harbor MUST verify the account signature on every mutating frame (workflows_save /
  * remove / run) via guardControl BEFORE calling save/remove/run here — a forged save
  * would plant a script step, a forged run would execute one. `list`/`get` are read-only.
  *
@@ -48,7 +48,7 @@ export interface WorkflowsControl {
   save(draft: unknown): { ok: boolean; message?: string; id?: string };
   // Remove a workflow by id or name. ok:false when nothing matched.
   remove(idOrName: string): { ok: boolean; message?: string };
-  // Run a workflow now (fire-and-forget on the daemon). ok:false when not found or the
+  // Run a workflow now (fire-and-forget on the harbor). ok:false when not found or the
   // runner isn't wired.
   run(idOrName: string): { ok: boolean; message?: string };
 }
@@ -72,7 +72,7 @@ function draftId(draft: unknown): string | undefined {
 }
 
 export function makeWorkflowsControl(opts: {
-  // Fire a workflow now — injected by the daemon (it owns the runner + its seams).
+  // Fire a workflow now — injected by the harbor (it owns the runner + its seams).
   // Absent → run is reported unavailable rather than silently dropped (mirrors routines).
   runNow?: (wf: Workflow) => void;
 }): WorkflowsControl {

package/src/routines/delivery.ts

@@ -2,13 +2,13 @@ import type { Routine } from "./schema.ts";
 import { webhookName } from "./schema.ts";
 import { writeRoutineOutput, addNotice } from "./store.ts";
 
-// A relay pusher, injected by the daemon. Given the finished result it either
+// A relay pusher, injected by the harbor. Given the finished result it either
 // forwards it to an attached controller immediately ("live") or persists it to the
 // pending-relay queue to flush when the app next attaches ("queued"). Either way the
 // result is durably accounted for, so delivery doesn't add a notice backstop for it.
 export type RelayPusher = (routine: Routine, content: string) => "live" | "queued";
 
-// A cloud-outbox pusher, injected by the daemon. Seals the result to the account's
+// A cloud-outbox pusher, injected by the harbor. Seals the result to the account's
 // outbox public key and POSTs the ciphertext to the server (E2EE store-and-forward),
 // or buffers it durably on failure. Returns "sent" when the server accepted it,
 // "queued" when it was persisted for a later flush — either way the result is
@@ -31,7 +31,7 @@ export interface DeliveryContext {
   // Named endpoints for "webhook:<name>" delivery entries; results POST here.
   webhooks?: Record<string, WebhookTarget>;
   // Scrubs secrets from anything leaving the machine. Webhook bodies always pass
-  // through this when provided (the daemon wires in redactText).
+  // through this when provided (the harbor wires in redactText).
   redact?: (text: string) => string;
   // Injectable for tests; defaults to global fetch.
   fetchImpl?: typeof fetch;
@@ -39,7 +39,7 @@ export interface DeliveryContext {
 
 export interface DeliveryReport {
   // Channels that actually delivered (email is handled inside the agent run, so it
-  // never appears here — see the daemon). Failed webhooks show as
+  // never appears here — see the harbor). Failed webhooks show as
   // "webhook:<name>(failed)" and leave a notice so the result isn't silently lost.
   delivered: string[];
   // Absolute path to latest.md when file delivery ran.
@@ -101,7 +101,7 @@ async function postWebhook(
 // result is never silently lost. `webhook:<name>` POSTs the (redacted) result to a
 // named endpoint from config; a failed or unconfigured webhook leaves a notice.
 // `email` is intentionally not handled here: it is fulfilled inside the agent turn
-// (the daemon adds the Gmail tool + an instruction to the prompt) so plaintext
+// (the harbor adds the Gmail tool + an instruction to the prompt) so plaintext
 // egress stays an explicit, gated action.
 export async function deliver(
   routine: Routine,
@@ -127,7 +127,7 @@ export async function deliver(
   }
 
   // Relay: pushed live to an attached controller, or queued to flush when the app
-  // next attaches (the daemon persists that queue, so it's durable either way). Only
+  // next attaches (the harbor persists that queue, so it's durable either way). Only
   // when no pusher is wired at all do we fall back to a notice so it isn't lost.
   if (wants.has("relay")) {
     const pushed = ctx.pushRelay?.(routine, content);

package/src/routines/schema.ts

@@ -27,7 +27,7 @@ export function webhookName(entry: string): string | null {
 }
 
 // A saved, unattended agent task. Persisted in routines.json and executed by the
-// daemon when its trigger comes due. A routine's trigger is EITHER recurring (a
+// harbor when its trigger comes due. A routine's trigger is EITHER recurring (a
 // cron expression) or one-off (`at`, a specific datetime) — exactly one is set.
 export const Routine = z
   .object({
@@ -48,14 +48,14 @@ export const Routine = z
     model: z.string().optional(),
     // Where to deliver the result. Defaults to on-box file output.
     delivery: z.array(DeliveryEntry).default(["file"]),
-    // Optional tool allow-subset. Unset → the safe read/web set (see daemon). Entries
+    // Optional tool allow-subset. Unset → the safe read/web set (see harbor). Entries
     // may be builtin names ("read") or MCP selectors — "<server>__<tool>" exact or
     // "<server>__*" for a whole server (see routines/toolSelect.ts). Selected MCP
     // tools run unattended under the auto-approve gate, so grant the minimum needed.
     tools: z.array(z.string()).optional(),
     // Paused routines stay in the file but never fire.
     enabled: z.boolean().default(true),
-    // Bookkeeping, updated by the daemon after each run.
+    // Bookkeeping, updated by the harbor after each run.
     lastRun: z.string().optional(),
     lastStatus: z.enum(["ok", "error"]).optional(),
     lastError: z.string().optional(),

package/src/routines/store.ts

@@ -20,7 +20,7 @@ function slug(name: string): string {
   return name.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "routine";
 }
 
-// A stable relay terminal id for the daemon, persisted so it reappears as the same
+// A stable relay terminal id for the harbor, persisted so it reappears as the same
 // "Privateer Routines" terminal in the app across restarts (rather than a fresh
 // random terminal each boot). Random on first use so it stays unique per install —
 // the relay routes on this id with no user namespacing, so a shared constant could
@@ -53,7 +53,7 @@ export function loadRoutines(): Routine[] {
   try {
     return RoutineFile.parse(JSON.parse(readFileSync(path, "utf8"))).routines;
   } catch {
-    // A corrupt or hand-edited file shouldn't crash the daemon; treat as empty.
+    // A corrupt or hand-edited file shouldn't crash the harbor; treat as empty.
     return [];
   }
 }
@@ -160,7 +160,7 @@ export function drainNotices(): RoutineNotice[] {
 }
 
 // A relay result produced while no controller was attached, held until the app
-// next connects. Persisted (not just in-memory) so it survives a daemon restart.
+// next connects. Persisted (not just in-memory) so it survives a harbor restart.
 export interface PendingRelay {
   routine: string;
   at: string; // ISO timestamp

package/src/routines/trigger.ts

@@ -16,7 +16,7 @@ export function triggerError(t: Trigger): string | null {
 
 // The fire time to store as `nextRun`. For cron: the next match strictly after
 // `from`. For a one-off: the fixed `at` time as-is (even if already past, so a
-// missed one-off still fires once when the daemon comes back). Null if unparseable.
+// missed one-off still fires once when the harbor comes back). Null if unparseable.
 export function computeNextRun(t: Trigger, from: Date = new Date()): Date | null {
   if (t.cron) return cronNext(t.cron, from);
   if (t.at) {

package/src/tools/routine.ts

@@ -1,6 +1,6 @@
 // The `create_routine` tool — lets the agent turn "summarize the news every morning"
-// or "remind me at 3pm tomorrow" into a saved routine the scheduler daemon runs
-// unattended (see src/daemon). Ported from tree-cli/src/tools/routine.ts, adapted to
+// or "remind me at 3pm tomorrow" into a saved routine the scheduler harbor runs
+// unattended (see src/harbor). Ported from tree-cli/src/tools/routine.ts, adapted to
 // Pi's registerTool (TypeBox schema) with the in-tool ctx.gate.request removed: in
 // the Pi model our permission-gate extension gates the tool_call itself (classify.ts
 // gives it a "Create routine" prompt + flags email/webhook egress).
@@ -11,7 +11,7 @@ import { configPath } from "../config/paths.ts";
 import { newRoutineId, webhookName, type Routine } from "../routines/schema.ts";
 import { triggerError, computeNextRun, describeTrigger } from "../routines/trigger.ts";
 import { upsertRoutine } from "../routines/store.ts";
-import { sendToDaemon, DaemonNotRunningError } from "../daemon/ipc.ts";
+import { sendToHarbor, HarborNotRunningError } from "../harbor/ipc.ts";
 
 const KNOWN_CHANNELS = new Set(["file", "relay", "notice", "cloud", "email"]);
 
@@ -106,20 +106,20 @@ export const routineToolDefinition = {
       nextRun: next?.toISOString(),
     };
 
-    // Hand to the running daemon (it validates + schedules); fall back to writing the
-    // file so the routine persists until the daemon starts.
+    // Hand to the running harbor (it validates + schedules); fall back to writing the
+    // file so the routine persists until the harbor starts.
     try {
-      const res = await sendToDaemon({ cmd: "add", routine });
+      const res = await sendToHarbor({ cmd: "add", routine });
       if (!res.ok) return text(`Error saving routine: ${res.message ?? "unknown"}`);
       return text(
         `Created routine "${name}" (${describeTrigger({ cron, at })}). ` +
           `Next run ${next ? next.toLocaleString() : "unknown"}, delivery: ${chans.join(", ")}.`,
       );
     } catch (e) {
-      if (e instanceof DaemonNotRunningError) {
+      if (e instanceof HarborNotRunningError) {
         upsertRoutine(routine);
         return text(
-          `Saved routine "${name}" (${describeTrigger({ cron, at })}), but the scheduler daemon isn't ` +
+          `Saved routine "${name}" (${describeTrigger({ cron, at })}), but the scheduler harbor isn't ` +
             `running yet, so it won't fire until you start it.`,
         );
       }

package/src/util/fileMentions.ts

@@ -0,0 +1,232 @@
+// @file mentions — let a prompt reference files on the terminal's machine by typing
+// `@path`. Used by BOTH surfaces:
+//   • the local REPL (readline tab-completion + resolution at submit)
+//   • the app composer, driven over the relay (a files_search palette; the SAME
+//     resolution runs on the terminal when the prompt lands)
+//
+// The mention token stays INLINE in the prompt (so the model sees the reference in
+// context) and each referenced file's content is appended after it as a
+// <file name="…">…</file> block — text inline, images as real attachments. This
+// mirrors Pi's own @file CLI-arg expander (cli/file-processor) but is a library, not
+// a process: it never exits on a bad path, and it is CWD-CONSTRAINED.
+//
+// SECURITY: resolution is a client-side text expansion that bypasses the permission
+// gate (unlike the Read tool). A remote driver is the account owner, but a
+// gate-bypassing arbitrary read (`@/etc/shadow`, `@../secrets`) is exactly what we
+// must not grant. So every token MUST resolve inside cwd — anything that escapes the
+// cwd subtree (absolute paths, `..`, symlink targets outside) is skipped, not read.
+// The same rule bounds the relay file-search so filenames outside the project never
+// leak to the controller.
+
+import { readFile, readdir, realpath, stat } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+
+/** An image attachment, shaped for AgentSession.prompt()'s `images` option (Pi's ImageContent). */
+export interface MentionImage {
+  type: "image";
+  data: string; // base64
+  mimeType: string;
+}
+
+export interface ResolvedMentions {
+  /** The prompt with each referenced file's content appended as a <file> block. */
+  text: string;
+  /** Image attachments to pass via prompt options.images. */
+  images: MentionImage[];
+  /** cwd-relative paths that were successfully attached. */
+  resolved: string[];
+  /** Raw tokens that couldn't be attached (missing / outside cwd / a dir / too big). */
+  skipped: string[];
+}
+
+// Inline text stays reasonable; a giant file would blow the context and the relay.
+const MAX_TEXT_BYTES = 256 * 1024; // 256 KB per text file inlined
+const MAX_IMAGE_BYTES = 5 * 1024 * 1024; // 5 MB per image before base64
+
+const IMAGE_EXT: Record<string, string> = {
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+};
+
+const extOf = (name: string): string => {
+  const dot = name.lastIndexOf(".");
+  return dot > 0 ? name.slice(dot + 1).toLowerCase() : "";
+};
+
+// Trailing characters that are almost always sentence punctuation, not part of a
+// filename — trimmed from a token if the trimmed form resolves and the raw doesn't.
+const TRAIL_PUNCT = /[.,;:!?)\]}>]+$/;
+
+// A mention is `@` at start-of-string or after whitespace, then either a "quoted path"
+// (allows spaces) or a run of non-whitespace path characters. Capturing group 2 is the
+// path (quoted contents via group 3, else the bare run).
+const MENTION_RE = /(^|\s)@("([^"]+)"|[^\s@]+)/g;
+
+/** Pull the raw path tokens out of a prompt (order-preserving, de-duplicated). */
+export function parseMentions(text: string): string[] {
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const m of text.matchAll(MENTION_RE)) {
+    const raw = m[3] ?? m[2]; // quoted contents, else the bare run
+    if (raw && !seen.has(raw)) {
+      seen.add(raw);
+      out.push(raw);
+    }
+  }
+  return out;
+}
+
+// Resolve a raw token to an absolute path inside cwd, or null if it escapes / doesn't
+// exist. Follows the real (symlink-resolved) path and re-checks containment so a
+// symlink inside cwd pointing outside can't be used to read out.
+async function resolveInsideCwd(raw: string, cwd: string): Promise<string | null> {
+  // A relative path only — an absolute token is an escape attempt by definition.
+  if (isAbsolute(raw)) return null;
+  const abs = resolve(cwd, raw);
+  const within = (p: string): boolean => p === cwd || p.startsWith(cwd + sep);
+  if (!within(abs)) return null; // `..` climbed out
+  try {
+    const real = await realpath(abs);
+    // realpath the cwd too, so a symlinked project root still matches.
+    const realCwd = await realpath(cwd).catch(() => cwd);
+    if (real !== realCwd && !real.startsWith(realCwd + sep)) return null;
+    return real;
+  } catch {
+    return null; // doesn't exist
+  }
+}
+
+// Try the token as-is, then progressively trimmed of trailing punctuation, returning
+// the first form that resolves to a readable file inside cwd.
+async function resolveToken(raw: string, cwd: string): Promise<string | null> {
+  const candidates = [raw];
+  const trimmed = raw.replace(TRAIL_PUNCT, "");
+  if (trimmed && trimmed !== raw) candidates.push(trimmed);
+  for (const c of candidates) {
+    const abs = await resolveInsideCwd(c, cwd);
+    if (abs) return abs;
+  }
+  return null;
+}
+
+/**
+ * Expand every `@path` mention in `text` into appended <file> blocks (text) plus image
+ * attachments. Unresolved mentions are left inline verbatim and reported in `skipped`.
+ * The returned `text` equals the input when there are no resolvable mentions.
+ */
+export async function resolveMentions(text: string, cwd: string): Promise<ResolvedMentions> {
+  const tokens = parseMentions(text);
+  const images: MentionImage[] = [];
+  const resolved: string[] = [];
+  const skipped: string[] = [];
+  const blocks: string[] = [];
+  // resolveToken returns the symlink-resolved (real) absolute path, so relative paths
+  // must be computed against the real cwd — otherwise a symlinked cwd (e.g. /var →
+  // /private/var on macOS) yields a spurious `../../…` prefix.
+  const realCwd = await realpath(cwd).catch(() => cwd);
+
+  for (const raw of tokens) {
+    const abs = await resolveToken(raw, cwd);
+    if (!abs) { skipped.push(raw); continue; }
+    let st;
+    try { st = await stat(abs); } catch { skipped.push(raw); continue; }
+    if (!st.isFile() || st.size === 0) { skipped.push(raw); continue; }
+    const rel = relative(realCwd, abs) || basename(abs);
+    const mime = IMAGE_EXT[extOf(abs)];
+    try {
+      if (mime) {
+        if (st.size > MAX_IMAGE_BYTES) { skipped.push(raw); continue; }
+        const buf = await readFile(abs);
+        images.push({ type: "image", data: buf.toString("base64"), mimeType: mime });
+        // A bare reference so the model ties the image to the path it saw inline.
+        blocks.push(`<file name="${rel}"></file>`);
+      } else {
+        if (st.size > MAX_TEXT_BYTES) { skipped.push(raw); continue; }
+        const content = await readFile(abs, "utf-8");
+        blocks.push(`<file name="${rel}">\n${content}\n</file>`);
+      }
+      resolved.push(rel);
+    } catch {
+      skipped.push(raw);
+    }
+  }
+
+  const out = blocks.length ? `${text}\n\n${blocks.join("\n")}` : text;
+  return { text: out, images, resolved, skipped };
+}
+
+// ── autocomplete ──────────────────────────────────────────────────────────────────
+
+export interface FileMatch {
+  /** cwd-relative path (directories carry a trailing "/"). */
+  path: string;
+  isDir: boolean;
+}
+
+// Directory entries we never surface as suggestions (noise / not project files).
+const IGNORE_DIRS = new Set([".git", "node_modules", ".DS_Store"]);
+
+/**
+ * List up to `limit` files/dirs inside cwd whose path matches `query` — the text the
+ * user typed after `@`. A query with a trailing "/" (or ending at a real dir) lists
+ * that directory's contents; otherwise it prefix-matches the basename within the
+ * query's parent dir. Case-insensitive. CWD-constrained: a query that escapes cwd
+ * returns nothing.
+ */
+export async function searchFiles(query: string, cwd: string, limit = 50): Promise<FileMatch[]> {
+  const q = query ?? "";
+  if (isAbsolute(q)) return [];
+  // Split into the directory to scan and the basename prefix to filter by. A trailing
+  // slash means "list this dir", so the prefix is empty.
+  const endsWithSlash = q.endsWith("/");
+  const dirPart = endsWithSlash ? q : dirname(q);
+  const prefix = endsWithSlash ? "" : basename(q);
+  const scanRel = dirPart === "." ? "" : dirPart;
+  const scanAbs = resolve(cwd, scanRel);
+  // Containment check (mirror resolveInsideCwd, sync form — no realpath needed for a listing).
+  if (scanAbs !== cwd && !scanAbs.startsWith(cwd + sep)) return [];
+
+  let entries: import("node:fs").Dirent[];
+  try {
+    entries = await readdir(scanAbs, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const pfx = prefix.toLowerCase();
+  const matches: FileMatch[] = [];
+  for (const e of entries) {
+    if (IGNORE_DIRS.has(e.name)) continue;
+    if (pfx && !e.name.toLowerCase().startsWith(pfx)) continue;
+    if (e.name.startsWith(".") && !pfx.startsWith(".")) continue; // hide dotfiles unless asked
+    const isDir = e.isDirectory();
+    const rel = scanRel ? join(scanRel, e.name) : e.name;
+    matches.push({ path: isDir ? `${rel}/` : rel, isDir });
+    if (matches.length >= limit) break;
+  }
+  // Directories first, then alphabetical — the natural drill-down order.
+  matches.sort((a, b) => (a.isDir === b.isDir ? a.path.localeCompare(b.path) : a.isDir ? -1 : 1));
+  return matches;
+}
+
+/**
+ * A Node readline completer for `@`-mentions. Given the line up to the cursor, if it
+ * ends in an `@token`, returns full-line completions (readline replaces the whole
+ * line) so the mention drills into the cwd tree on Tab. Returns [[], line] when the
+ * cursor isn't in a mention, leaving other completion untouched.
+ */
+export async function completeMention(line: string, cwd: string): Promise<[string[], string]> {
+  // Find the last unquoted-ish `@token` that runs to the end of the line.
+  const m = /(^|\s)@([^\s@]*)$/.exec(line);
+  if (!m) return [[], line];
+  const token = m[2];
+  const tokenStart = m.index + m[1].length; // index of the '@'
+  const head = line.slice(0, tokenStart); // everything before '@'
+  const matches = await searchFiles(token, cwd, 100);
+  // Rebuild each as a full line: head + "@" + path. A single dir match keeps the
+  // trailing slash so the next Tab drills in.
+  const hits = matches.map((mm) => `${head}@${mm.path}`);
+  return [hits, line];
+}

package/src/workflows/expr.ts

@@ -1,4 +1,4 @@
 // The confined workflow expression/template engine now lives in the standalone
 // `privateer-workflow` package (its canonical home). This module re-exports it so the
-// daemon's existing `../workflows/expr.ts` import paths keep working unchanged.
+// harbor's existing `../workflows/expr.ts` import paths keep working unchanged.
 export * from "privateer-workflow/expr";

package/src/workflows/runner.ts

@@ -1,8 +1,8 @@
 // The workflow runner now lives in the standalone `privateer-workflow` package (its
-// canonical home). This module re-exports it so the daemon's existing
+// canonical home). This module re-exports it so the harbor's existing
 // `../workflows/runner.ts` import paths keep working unchanged.
 //
-// The daemon wires the runner's injected RunnerDeps to its own capabilities (headless
-// runSession, relay approvals, gated child processes, the cloud outbox) in daemon/index.ts
+// The harbor wires the runner's injected RunnerDeps to its own capabilities (headless
+// runSession, relay approvals, gated child processes, the cloud outbox) in harbor/index.ts
 // — that seam is unchanged; only the engine's source moved out to the shared package.
 export * from "privateer-workflow/runner";

package/src/workflows/schema.ts

@@ -1,5 +1,5 @@
 // The declarative workflow schema now lives in the standalone `privateer-workflow` package
-// (its canonical home). This module re-exports it so the daemon's existing
+// (its canonical home). This module re-exports it so the harbor's existing
 // `../workflows/schema.ts` import paths (schema.ts is also the store's dependency) keep
 // working unchanged.
 export * from "privateer-workflow/schema";

package/src/workflows/store.ts

@@ -52,7 +52,7 @@ function parseWorkflow(raw: string): Workflow | null {
 }
 
 // All valid workflows on disk, sorted by name. Corrupt/invalid files are skipped, not
-// thrown — a hand-mangled file shouldn't take down the daemon or the app's list.
+// thrown — a hand-mangled file shouldn't take down the harbor or the app's list.
 export function loadWorkflows(): Workflow[] {
   const dir = workflowsDir();
   if (!existsSync(dir)) return [];