@davvidbaker/flambe-cli 0.1.0 → 0.1.2

package/src/local/store.mjs

@@ -3,7 +3,10 @@ import { mkdirSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
 
-import { agentDisplayName } from './agents.mjs';
+import { pickName, usableName } from './agents.mjs';
+
+const LIFECYCLE_PHASES = ['B', 'E', 'S', 'R', 'X', 'J', 'V'];
+const OPEN_PHASES = ['B', 'R', 'X'];
 
 const SCHEMA = `
 PRAGMA foreign_keys = ON;
@@ -57,6 +60,10 @@ CREATE TABLE IF NOT EXISTS activities (
   weight INTEGER,
   agent_id TEXT,
   agent_name TEXT,
+  scheduled_start_ms INTEGER,
+  scheduled_end_ms INTEGER,
+  proposed_by_agent_id TEXT,
+  proposed_by_agent_name TEXT,
   export_id TEXT NOT NULL UNIQUE
 );
 
@@ -76,13 +83,6 @@ CREATE TABLE IF NOT EXISTS events (
   export_id TEXT NOT NULL UNIQUE
 );
 
-CREATE TABLE IF NOT EXISTS todos (
-  id INTEGER PRIMARY KEY,
-  user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
-  name TEXT NOT NULL,
-  description TEXT
-);
-
 CREATE TABLE IF NOT EXISTS mantras (
   id INTEGER PRIMARY KEY,
   user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
@@ -112,6 +112,17 @@ CREATE TABLE IF NOT EXISTS search_terms (
   timestamp_ms INTEGER NOT NULL
 );
 
+CREATE TABLE IF NOT EXISTS agents (
+  id INTEGER PRIMARY KEY,
+  user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  agent_id TEXT NOT NULL,
+  name TEXT NOT NULL,
+  name_source TEXT NOT NULL,
+  platform TEXT,
+  last_seen_ms INTEGER NOT NULL,
+  UNIQUE (user_id, agent_id)
+);
+
 CREATE TABLE IF NOT EXISTS observations (
   id INTEGER PRIMARY KEY,
   user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
@@ -127,6 +138,28 @@ CREATE TABLE IF NOT EXISTS observations (
 export const EXPORT_FORMAT = 'flambe-local-export';
 export const EXPORT_VERSION = 1;
 
+export const DEFAULT_CATEGORIES = [
+  { name: 'bug fixing', color_background: '#ff4747', color_text: '#000000' },
+  { name: 'research', color_background: '#cd94f1', color_text: '#000000' },
+  { name: 'cleaning', color_background: '#ffbd69', color_text: '#000000' },
+  { name: 'bug hunting', color_background: '#ef60ab', color_text: '#000000' },
+  { name: 'design', color_background: '#dce7ea', color_text: '#000000' },
+  { name: 'writing tests', color_background: '#50f035', color_text: '#000000' },
+  { name: 'toil', color_background: '#8b6125', color_text: '#ffffff' },
+  { name: 'analytics', color_background: '#f9f9f9', color_text: '#4598d6' },
+  { name: 'oss', color_background: '#60ef6c', color_text: '#000000' },
+  { name: 'enhancements', color_background: '#55defb', color_text: '#ffffff' },
+  { name: 'refactoring components', color_background: '#ffd368', color_text: '#000000' },
+  { name: 'Fundamentals', color_background: '#acefdb', color_text: '#000000' },
+  { name: 'jarring ui', color_background: '#f22d6a', color_text: '#ffffff' },
+  { name: 'writing', color_background: '#ffefce', color_text: '#000000' },
+  { name: 'risky', color_background: '#ff2a22', color_text: '#ffffff' },
+  { name: 'dependency upgrades', color_background: '#b58e38', color_text: '#ffffff' },
+  { name: 'shiny', color_background: '#f5ff86', color_text: '#000000' },
+  { name: 'performance', color_background: '#60efc7', color_text: '#000000' },
+  { name: 'learning', color_background: '#d3f791', color_text: '#000000' },
+];
+
 export function hashToken(rawToken) {
   return createHash('sha256').update(rawToken).digest('hex');
 }
@@ -147,6 +180,17 @@ export class LocalStore {
     this.db = new DatabaseSync(dbPath);
     this.db.exec('PRAGMA foreign_keys = ON');
     this.db.exec(SCHEMA);
+    this.db.exec('DROP TABLE IF EXISTS todos');
+    for (const column of [
+      'scheduled_start_ms INTEGER',
+      'scheduled_end_ms INTEGER',
+      'proposed_by_agent_id TEXT',
+      'proposed_by_agent_name TEXT',
+    ]) {
+      const name = column.split(' ')[0];
+      const exists = this.db.prepare('PRAGMA table_info(activities)').all().some(row => row.name === name);
+      if (!exists) this.db.exec(`ALTER TABLE activities ADD COLUMN ${column}`);
+    }
     this.#seed();
   }
 
@@ -225,6 +269,7 @@ export class LocalStore {
     this.db.prepare(
       'INSERT INTO threads (trace_id, name, rank, export_id) VALUES (?, ?, 0, ?)',
     ).run(traceId, 'Main', randomUUID());
+    this.#ensureDefaultCategories(userId);
     return this.getTrace(userId, traceId);
   }
 
@@ -294,6 +339,7 @@ export class LocalStore {
   }
 
   listCategories(userId) {
+    this.#ensureDefaultCategories(userId);
     return this.db.prepare(
       'SELECT id, name, color_background, color_text FROM categories WHERE user_id = ? ORDER BY id',
     ).all(userId);
@@ -329,47 +375,142 @@ export class LocalStore {
     return result.changes > 0;
   }
 
-  createActivity(userId, { traceId, threadId, activity, event, agentId, agentName, tokenName }) {
-    const thread = this.db.prepare(`
-      SELECT threads.id, threads.trace_id
-      FROM threads
-      JOIN traces ON traces.id = threads.trace_id
-      WHERE threads.id = ? AND threads.trace_id = ? AND traces.user_id = ?
-    `).get(Number(threadId), Number(traceId), userId);
-    if (!thread) return { error: 'not_found' };
+  /**
+   * Resolve (and if needed name) the agent behind `agentId` for this user, mirroring
+   * FlambeNext.Agents.identify. `assigned` is true only when a name was coined now.
+   */
+  identifyAgent(userId, agentId, providedName, providedPlatform) {
+    if (typeof agentId !== 'string' || agentId.length === 0 || agentId.length > 200) return null;
+    const provided = usableName(providedName) ? providedName.trim() : null;
+    const platformGiven = usableName(providedPlatform) ? providedPlatform.trim() : null;
+    const now = Date.now();
+    const existing = this.db.prepare('SELECT * FROM agents WHERE user_id = ? AND agent_id = ?').get(userId, agentId);
+
+    if (existing) {
+      const name = provided && provided !== existing.name ? provided : existing.name;
+      const platform = platformGiven ?? existing.platform ?? null;
+      this.db.prepare('UPDATE agents SET name = ?, name_source = ?, platform = ?, last_seen_ms = ? WHERE id = ?')
+        .run(name, provided && provided !== existing.name ? 'provided' : existing.name_source, platform, now, existing.id);
+      return { agent_id: agentId, name, platform, assigned: false };
+    }
+
+    const taken = this.db.prepare('SELECT name FROM agents WHERE user_id = ?').all(userId).map(row => row.name);
+    const name = provided ?? pickName(agentId, taken);
+    this.db.prepare('INSERT INTO agents (user_id, agent_id, name, name_source, platform, last_seen_ms) VALUES (?, ?, ?, ?, ?, ?)')
+      .run(userId, agentId, name, provided ? 'provided' : 'assigned', platformGiven, now);
+    return { agent_id: agentId, name, platform: platformGiven, assigned: provided === null };
+  }
+
+  listAgents(userId) {
+    return this.db.prepare('SELECT agent_id, name, name_source, platform, last_seen_ms FROM agents WHERE user_id = ? ORDER BY last_seen_ms DESC, id')
+      .all(userId);
+  }
+
+  /** Newest running activity in the trace, optionally for one agent or thread. */
+  newestActiveActivity(traceId, { agentId, threadId } = {}) {
+    const placeholders = LIFECYCLE_PHASES.map(() => '?').join(',');
+    const open = OPEN_PHASES.map(() => '?').join(',');
+    const rows = this.db.prepare(`
+      WITH latest AS (
+        SELECT activity_id, phase, timestamp_ms, id,
+               ROW_NUMBER() OVER (PARTITION BY activity_id ORDER BY timestamp_ms DESC, id DESC) AS rn
+        FROM events
+        WHERE trace_id = ? AND activity_id IS NOT NULL AND phase IN (${placeholders})
+      )
+      SELECT activities.id, activities.parent_id, activities.thread_id, activities.agent_id
+      FROM latest
+      JOIN activities ON activities.id = latest.activity_id
+      WHERE latest.rn = 1 AND latest.phase IN (${open})
+        ${agentId ? 'AND activities.agent_id = ?' : ''}
+        ${threadId ? 'AND activities.thread_id = ?' : ''}
+      ORDER BY latest.timestamp_ms DESC, latest.id DESC
+      LIMIT 1
+    `).all(
+      Number(traceId), ...LIFECYCLE_PHASES, ...OPEN_PHASES,
+      ...(agentId ? [agentId] : []), ...(threadId ? [Number(threadId)] : []),
+    );
+    return rows[0] ?? null;
+  }
+
+  /**
+   * Create an activity. With `reduce` (agent requests, ADR-012) the deterministic reducer
+   * rules apply: an absent parent_id infers this agent's newest active activity, a child
+   * lives in its parent's thread and inherits categories, and thread_id may be omitted.
+   */
+  createActivity(userId, { traceId, threadId, activity, event, agent, reduce = false }) {
+    const trace = this.db.prepare('SELECT id FROM traces WHERE id = ? AND user_id = ?').get(Number(traceId), userId);
+    if (!trace) return { error: 'not_found' };
 
-    let parentId = activity.parent_id ?? null;
-    if (parentId != null) {
-      const parent = this.db.prepare(
-        'SELECT id FROM activities WHERE id = ? AND thread_id = ?',
-      ).get(Number(parentId), thread.id);
-      if (!parent) return { error: 'not_found' };
-      parentId = parent.id;
+    const notes = { parent_source: 'root', thread_source: 'request', categories_source: 'none' };
+    let parentRow = null;
+    let parentId = null;
+
+    if (Object.hasOwn(activity, 'parent_id') && activity.parent_id != null) {
+      parentRow = this.db.prepare(`
+        SELECT activities.id, activities.thread_id FROM activities
+        JOIN threads ON threads.id = activities.thread_id
+        WHERE activities.id = ? AND threads.trace_id = ?
+      `).get(Number(activity.parent_id), trace.id);
+      if (!parentRow) return { error: 'not_found' };
+      notes.parent_source = 'explicit';
+    } else if (reduce && !Object.hasOwn(activity, 'parent_id')) {
+      const requestedThread = threadId == null ? this.#defaultThread(trace.id)?.id : Number(threadId);
+      parentRow = agent?.agent_id
+        ? this.newestActiveActivity(trace.id, { agentId: agent.agent_id })
+        : this.newestActiveActivity(trace.id, { threadId: requestedThread });
+      if (parentRow) notes.parent_source = 'inferred';
     }
 
-    const categoryIds = Array.isArray(activity.categories) ? activity.categories.map(Number) : [];
+    let thread;
+    if (parentRow) {
+      thread = this.db.prepare('SELECT id, trace_id FROM threads WHERE id = ?').get(parentRow.thread_id);
+      notes.thread_source = 'parent';
+      parentId = parentRow.id;
+    } else if (threadId == null) {
+      if (!reduce) return { error: 'not_found' };
+      thread = this.#defaultThread(trace.id);
+      notes.thread_source = 'default';
+    } else {
+      thread = this.db.prepare('SELECT id, trace_id FROM threads WHERE id = ? AND trace_id = ?').get(Number(threadId), trace.id);
+    }
+    if (!thread) return { error: 'not_found' };
+    if (!reduce && parentRow && parentRow.thread_id !== thread.id) return { error: 'not_found' };
+
+    let categoryIds = Array.isArray(activity.categories) ? activity.categories.map(Number) : [];
     if (categoryIds.length > 0) {
       const found = this.db.prepare(
         `SELECT id FROM categories WHERE user_id = ? AND id IN (${categoryIds.map(() => '?').join(',')})`,
       ).all(userId, ...categoryIds);
       if (found.length !== new Set(categoryIds).size) return { error: 'not_found' };
+      notes.categories_source = 'request';
+    } else if (reduce && parentId != null) {
+      categoryIds = this.db.prepare('SELECT category_id FROM activities_categories WHERE activity_id = ?')
+        .all(parentId).map(row => row.category_id);
+      if (categoryIds.length > 0) notes.categories_source = 'parent';
     }
 
-    const agent = agentId
-      ? { agent_id: agentId, agent_name: agentDisplayName(agentId, agentName, tokenName) }
+    const agentColumns = agent?.agent_id
+      ? { agent_id: agent.agent_id, agent_name: agent.name }
       : { agent_id: null, agent_name: null };
 
     const inserted = this.db.prepare(`
-      INSERT INTO activities (thread_id, parent_id, name, description, weight, agent_id, agent_name, export_id)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      INSERT INTO activities (
+        thread_id, parent_id, name, description, weight, agent_id, agent_name,
+        scheduled_start_ms, scheduled_end_ms, proposed_by_agent_id, proposed_by_agent_name, export_id
+      )
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `).run(
       thread.id,
       parentId,
       activity.name,
       activity.description ?? null,
       activity.weight ?? null,
-      agent.agent_id,
-      agent.agent_name,
+      agentColumns.agent_id,
+      agentColumns.agent_name,
+      activity.scheduled_start_ms ?? null,
+      activity.scheduled_end_ms ?? null,
+      activity.proposed_by_agent_id ?? agentColumns.agent_id,
+      activity.proposed_by_agent_name ?? agentColumns.agent_name,
       randomUUID(),
     );
     const activityId = Number(inserted.lastInsertRowid);
@@ -395,9 +536,46 @@ export class LocalStore {
         thread_id: thread.id,
       },
       event: { id: Number(eventRow.lastInsertRowid), phase: event.phase },
+      ...(reduce ? { reducer: notes } : {}),
     };
   }
 
+  createUnstarted(userId, { traceId, name, description, weight, agent, scheduledStart, scheduledEnd }) {
+    const thread = this.#defaultThread(Number(traceId));
+    if (!thread) return { error: 'not_found' };
+    const trace = this.db.prepare('SELECT id FROM traces WHERE id = ? AND user_id = ?').get(thread.trace_id, userId);
+    if (!trace) return { error: 'not_found' };
+    const inserted = this.db.prepare(`
+      INSERT INTO activities (
+        thread_id, parent_id, name, description, weight, agent_id, agent_name,
+        scheduled_start_ms, scheduled_end_ms, proposed_by_agent_id, proposed_by_agent_name, export_id
+      ) VALUES (?, NULL, ?, ?, ?, NULL, NULL, ?, ?, ?, ?, ?)
+    `).run(
+      thread.id, name, description ?? null, weight ?? null,
+      scheduledStart ?? null, scheduledEnd ?? null,
+      agent?.agent_id ?? null, agent?.name ?? null, randomUUID(),
+    );
+    return { activity: { id: Number(inserted.lastInsertRowid), name, thread_id: thread.id, parent_id: null } };
+  }
+
+  listUnstarted(traceId) {
+    return this.db.prepare(`
+      SELECT activities.* FROM activities
+      JOIN threads ON threads.id = activities.thread_id
+      WHERE threads.trace_id = ?
+        AND NOT EXISTS (
+          SELECT 1 FROM events
+          WHERE events.activity_id = activities.id
+            AND events.phase IN ('B','R','X','S','E','J','V')
+        )
+      ORDER BY activities.id
+    `).all(Number(traceId));
+  }
+
+  #defaultThread(traceId) {
+    return this.db.prepare('SELECT id, trace_id FROM threads WHERE trace_id = ? ORDER BY rank, id LIMIT 1').get(traceId) ?? null;
+  }
+
   getActivity(userId, id) {
     const row = this.db.prepare(`
       SELECT activities.*
@@ -414,6 +592,8 @@ export class LocalStore {
       weight: row.weight,
       parent_id: row.parent_id,
       thread_id: row.thread_id,
+      agent_id: row.agent_id ?? null,
+      agent_name: row.agent_name ?? null,
     };
   }
 
@@ -429,6 +609,13 @@ export class LocalStore {
       WHERE id = ?
     `).run(attrs.name ?? null, attrs.description ?? null, attrs.weight ?? null, attrs.parent_id ?? null, current.id);
 
+    if (Object.prototype.hasOwnProperty.call(attrs, 'agent_id')) {
+      const agentId = attrs.agent_id == null || attrs.agent_id === '' ? null : String(attrs.agent_id);
+      const agentName = agentId == null ? null : this.#activityAgentName(userId, agentId, attrs);
+      this.db.prepare('UPDATE activities SET agent_id = ?, agent_name = ? WHERE id = ?')
+        .run(agentId, agentName, current.id);
+    }
+
     if (Array.isArray(attrs.category_ids)) {
       this.db.prepare('DELETE FROM activities_categories WHERE activity_id = ?').run(current.id);
       for (const categoryId of attrs.category_ids) {
@@ -512,7 +699,6 @@ export class LocalStore {
       username: user.username,
       traces: this.listTraces(userId),
       categories: this.listCategories(userId),
-      todos: this.db.prepare('SELECT id, name, description FROM todos WHERE user_id = ?').all(userId),
       mantras: this.db.prepare('SELECT id, name, timestamp_ms FROM mantras WHERE user_id = ? ORDER BY id').all(userId)
         .map(row => ({ id: row.id, name: row.name, timestamp: isoFromMs(row.timestamp_ms) })),
       attentionShifts: this.db.prepare(
@@ -538,17 +724,14 @@ export class LocalStore {
         timestamp: isoFromMs(row.timestamp_ms),
       })),
       observations: this.listObservations(userId),
+      agents: this.listAgents(userId).map(agent => ({
+        agent_id: agent.agent_id,
+        name: agent.name,
+        platform: agent.platform ?? null,
+      })),
     };
   }
 
-  createTodo(userId, attrs) {
-    const result = this.db.prepare(
-      'INSERT INTO todos (user_id, name, description) VALUES (?, ?, ?)',
-    ).run(userId, attrs.name, attrs.description ?? null);
-    return this.db.prepare('SELECT id, name, description FROM todos WHERE id = ?')
-      .get(Number(result.lastInsertRowid));
-  }
-
   createMantra(userId, attrs) {
     const timestamp = Number(attrs.timestamp_integer ?? Date.now());
     const result = this.db.prepare(
@@ -676,6 +859,24 @@ export class LocalStore {
     };
   }
 
+  #activityAgentName(userId, agentId, attrs) {
+    const known = this.db.prepare(
+      'SELECT name FROM agents WHERE user_id = ? AND agent_id = ?',
+    ).get(userId, agentId);
+    if (known?.name) return known.name;
+    const snapshot = this.db.prepare(`
+      SELECT activities.agent_name FROM activities
+      JOIN threads ON threads.id = activities.thread_id
+      JOIN traces ON traces.id = threads.trace_id
+      WHERE traces.user_id = ? AND activities.agent_id = ?
+        AND activities.agent_name IS NOT NULL AND activities.agent_name != ''
+      LIMIT 1
+    `).get(userId, agentId);
+    if (snapshot?.agent_name) return snapshot.agent_name;
+    if (typeof attrs.agent_name === 'string' && attrs.agent_name !== '') return attrs.agent_name;
+    return agentId;
+  }
+
   #eventPayload(event) {
     const categoryIds = event.activity_id == null
       ? []
@@ -713,6 +914,27 @@ export class LocalStore {
     };
   }
 
+  #ensureDefaultCategories(userId) {
+    const have = new Set(
+      this.db.prepare('SELECT lower(name) AS name FROM categories WHERE user_id = ?')
+        .all(userId)
+        .map(row => row.name),
+    );
+    const insert = this.db.prepare(
+      'INSERT INTO categories (user_id, name, color_background, color_text, export_id) VALUES (?, ?, ?, ?, ?)',
+    );
+    for (const category of DEFAULT_CATEGORIES) {
+      if (have.has(category.name.toLowerCase())) continue;
+      insert.run(
+        userId,
+        category.name,
+        category.color_background,
+        category.color_text,
+        randomUUID(),
+      );
+    }
+  }
+
   #seed() {
     const user = this.db.prepare('SELECT id FROM users WHERE id = 1').get();
     if (user) return;
@@ -730,6 +952,7 @@ export class LocalStore {
       this.db.prepare(
         'INSERT INTO threads (trace_id, name, rank, export_id) VALUES (?, ?, 0, ?)',
       ).run(Number(trace.lastInsertRowid), 'Main', randomUUID());
+      this.#ensureDefaultCategories(1);
       this.db.exec('COMMIT');
     } catch (error) {
       this.db.exec('ROLLBACK');

package/src/questions.mjs

@@ -0,0 +1,48 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+// A question the reducer asked and the worker has not answered yet (ADR-014).
+// One open question per trace. The CLI reminds; it never refuses the next command.
+
+export function defaultQuestionsPath() {
+  return join(homedir(), '.flambe', 'open-questions.json');
+}
+
+export function readOpenQuestion(traceId, path = defaultQuestionsPath()) {
+  if (!traceId) return undefined;
+  const stored = readAll(path)[String(traceId)];
+  if (!stored || typeof stored.reply !== 'string' || !stored.reply.trim()) return undefined;
+  return { activityId: stored.activityId, reply: stored.reply };
+}
+
+export function rememberQuestion(traceId, { activityId, reply }, path = defaultQuestionsPath()) {
+  if (!traceId || !reply) return;
+  const all = { ...readAll(path), [String(traceId)]: { activityId, reply } };
+  writeAll(path, all);
+}
+
+export function clearQuestion(traceId, path = defaultQuestionsPath()) {
+  if (!traceId) return;
+  const all = readAll(path);
+  if (!(String(traceId) in all)) return;
+  delete all[String(traceId)];
+  writeAll(path, all);
+}
+
+function readAll(path) {
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeAll(path, questions) {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(questions, null, 2)}\n`);
+  renameSync(tmp, path);
+}

package/src/queue.mjs

@@ -28,14 +28,19 @@ function emptyState() {
 }
 
 export class FlambeQueue {
-  constructor({ baseUrl, traceId, path = defaultQueuePath() }) {
+  constructor({ baseUrl, traceId, agentId, path = defaultQueuePath() }) {
     this.baseUrl = baseUrl;
     this.traceId = Number(traceId);
+    this.agentId = agentId;
     this.path = path;
   }
 
   matches(entry) {
-    return entry.baseUrl === this.baseUrl && entry.traceId === this.traceId;
+    return entry.baseUrl === this.baseUrl
+      && entry.traceId === this.traceId
+      // Version-1 entries created before identity was recorded remain replayable.
+      // New entries may only be replayed by the worker that queued them.
+      && (entry.agentId === undefined || entry.agentId === this.agentId);
   }
 
   async read() {
@@ -70,6 +75,7 @@ export class FlambeQueue {
       type,
       baseUrl: this.baseUrl,
       traceId: this.traceId,
+      ...(this.agentId ? { agentId: this.agentId } : {}),
       ...(localId ? { localId } : {}),
       ...payload,
     });
@@ -107,7 +113,13 @@ export class FlambeQueue {
         } else if (entry.type === 'end' || entry.type === 'suspend' || entry.type === 'resume') {
           const activityId = state.aliases[entry.activityId] ?? entry.activityId;
           const post = { end, suspend, resume }[entry.type];
-          await post({ activityId, message: entry.message, timestamp: entry.timestamp });
+          await post({
+            activityId,
+            message: entry.message,
+            timestamp: entry.timestamp,
+            force: entry.force ?? false,
+            phase: entry.phase,
+          });
           if (entry.type === 'end') delete state.aliases[entry.activityId];
         } else if (entry.type === 'observe') {
           await observe(entry.input);

package/src/runtime.mjs

@@ -0,0 +1,23 @@
+/** Explicit transport boundary; never infer local-only intent from a URL. */
+export function runtimeConfig(env) {
+  const mode = env.FLAMBE_RUNTIME_MODE?.trim();
+  if (!mode) return {};
+  if (!['cloud', 'local_self_contained'].includes(mode)) {
+    throw new Error('FLAMBE_RUNTIME_MODE must be cloud or local_self_contained');
+  }
+  return { runtimeMode: mode };
+}
+
+export function assertRuntimeUrl(value, mode) {
+  if (mode !== 'local_self_contained') return;
+  let url;
+  try { url = new URL(value); } catch {
+    throw new Error('Self-contained mode requires a loopback HTTP URL');
+  }
+  // Numeric addresses avoid DNS resolution changing the trust boundary.
+  if (!['http:', 'https:'].includes(url.protocol)
+    || !['127.0.0.1', '[::1]'].includes(url.hostname)
+    || url.username || url.password) {
+    throw new Error('Self-contained mode requires 127.0.0.1 or [::1]; remote destinations are disabled');
+  }
+}