@frontera-sdk/cli 1.50.12 → 1.50.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/cli",
-  "version": "1.50.12",
+  "version": "1.50.13",
   "description": "The frontera CLI — scaffold, pull, save and deploy Frontera apps and automations.",
   "keywords": [
     "frontera",
@@ -39,14 +39,14 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.251",
-    "@frontera-sdk/functions": "1.50.12",
-    "@frontera-sdk/core": "1.50.12",
+    "@frontera-sdk/functions": "1.50.13",
+    "@frontera-sdk/core": "1.50.13",
     "ai": "^6.0.116",
     "gray-matter": "^4.0.3",
     "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "@frontera-sdk/forge-contracts": "1.50.12",
+    "@frontera-sdk/forge-contracts": "1.50.13",
     "@types/bun": "^1.3.14",
     "typescript": "^5.9.3"
   }

package/src/commands/agent/draft-changes.ts

@@ -0,0 +1,85 @@
+import type { PlatformApi } from '../../api/platform-api'
+
+/**
+ * Which sections of an agent's draft differ from what is live.
+ *
+ * Shared by `frontera agent diff` and by the Forge daemon, which records the
+ * answer on the touch a successful `agent apply` produced so the Preview pane
+ * can open the agent page on the section that changed rather than at the
+ * top. One implementation, so the CLI and the pane never disagree about what
+ * "changed" means.
+ */
+
+/** Server-managed bookkeeping a draft carries but never "changes". */
+const MANAGED = new Set([
+  'id', 'orgId', 'workspaceId', 'createdAt', 'updatedAt', 'createdBy',
+  'currentVersion', 'currentVersionId', 'draft', 'lifecycleStatus',
+])
+
+export type AgentDraftChanges =
+  | { hasDraft: false; published: boolean; changed: [] }
+  | { hasDraft: true; published: boolean; revision: number; changed: string[] }
+
+/**
+ * JSON with object keys in a fixed order, for comparison.
+ *
+ * `JSON.stringify` preserves insertion order, and the draft snapshot and the
+ * live snapshot are built by different code paths — so the same
+ * `caseDefinition` serialises as `{metrics, objectSets, objectTypes}` on one
+ * side and `{objectTypes, metrics, objectSets}` on the other. Comparing the
+ * strings reported both as changed on a draft that had touched neither, which
+ * is the noise `agent diff` exists to avoid.
+ *
+ * Arrays keep their order: element order is meaningful in `stages` and
+ * `prompts`, where a reordering IS the change.
+ */
+export function stableStringify(value: unknown): string {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null'
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`
+  const entries = Object.entries(value as Record<string, unknown>).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+  return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(',')}}`
+}
+
+export async function agentDraftChanges(api: PlatformApi, id: string): Promise<AgentDraftChanges> {
+  // Both, before either branch answers: "the live version is current" is as
+  // wrong for an agent that has never published as "matches the live
+  // version" is, and that branch used to answer without ever looking.
+  const [draft, live] = await Promise.all([
+    api.agentDraft(id),
+    api.agent(id) as Promise<Record<string, unknown>>,
+  ])
+  const published = Boolean(live.currentVersion ?? live.currentVersionId)
+  if (!draft) return { hasDraft: false, published, changed: [] }
+
+  const liveConfig = (live.config ?? live) as Record<string, unknown>
+  const draftConfig = (draft.snapshot.config ?? {}) as Record<string, unknown>
+
+  /**
+   * A snapshot is `config` PLUS fifteen sibling sections. Only what the DRAFT
+   * declares is compared, never server-managed bookkeeping — taking the union
+   * reported `createdAt` as a pending change on a draft that touched nothing
+   * but a prompt. The live side of the sections comes from the live SNAPSHOT:
+   * `GET /config/agents/:id` returns flat scalars with every relation null, so
+   * every section would read as changed against it.
+   */
+  const liveSnapshot = await api.agentComposition(id).catch(() => null)
+  const draftSections = Object.fromEntries(
+    Object.entries(draft.snapshot).filter(([k]) => k !== 'config' && !MANAGED.has(k)),
+  )
+
+  const changed = [
+    ...Object.keys(draftConfig)
+      .filter((k) => !MANAGED.has(k))
+      .filter((k) => stableStringify(draftConfig[k]) !== stableStringify(liveConfig[k])),
+    // Only when the live snapshot could be read. Reporting every section as
+    // changed because one request failed would be worse than the silence
+    // this replaces.
+    ...(liveSnapshot
+      ? Object.keys(draftSections).filter(
+          (k) => stableStringify(draftSections[k]) !== stableStringify(liveSnapshot[k]),
+        )
+      : []),
+  ].sort()
+
+  return { hasDraft: true, published, revision: draft.revision, changed }
+}

package/src/commands/agent/index-commands.ts

@@ -6,6 +6,7 @@ import { table } from '../../table'
 import { flagBool, flagString, type Command, type CommandContext } from '../types'
 import { resolveWorkspaceId } from '../workspace-id'
 import { renderComposition, type Lookups } from './compose'
+import { agentDraftChanges } from './draft-changes'
 import { resolveAgentRef, type AgentRow } from './resolve'
 
 function api(ctx: CommandContext): PlatformApi {
@@ -90,25 +91,7 @@ async function readDocument(ctx: CommandContext): Promise<Record<string, unknown
   }
 }
 
-/**
- * JSON with object keys in a fixed order, for comparison.
- *
- * `JSON.stringify` preserves insertion order, and the draft snapshot and the
- * live snapshot are built by different code paths — so the same
- * `caseDefinition` serialises as `{metrics, objectSets, objectTypes}` on one
- * side and `{objectTypes, metrics, objectSets}` on the other. Comparing the
- * strings reported both as changed on a draft that had touched neither, which
- * is the noise `agent diff` exists to avoid.
- *
- * Arrays keep their order: element order is meaningful in `stages` and
- * `prompts`, where a reordering IS the change.
- */
-export function stableStringify(value: unknown): string {
-  if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null'
-  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`
-  const entries = Object.entries(value as Record<string, unknown>).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
-  return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(',')}}`
-}
+export { stableStringify } from './draft-changes'
 
 /** `agent_configs.agentId` — a slug, lowercase, the value every verb takes. */
 const SLUG_PATTERN = /^[a-z][a-z0-9-]*$/
@@ -371,13 +354,10 @@ const diff: Command = {
     // Both, before either branch answers: "the live version is current" is as
     // wrong for an agent that has never published as "matches the live
     // version" is, and that branch used to answer without ever looking.
-    const [draft, live] = await Promise.all([
-      t.api.agentDraft(t.id),
-      t.api.agent(t.id) as Promise<Record<string, unknown>>,
-    ])
-    const published = Boolean(live.currentVersion ?? live.currentVersionId)
+    const outcome = await agentDraftChanges(t.api, t.id)
+    const { published, changed } = outcome
 
-    if (!draft) {
+    if (!outcome.hasDraft) {
       return {
         data: { hasDraft: false, published, changed: [] },
         text: published
@@ -387,60 +367,16 @@ const diff: Command = {
             + `  Stage one with \`frontera agent apply ${t.ref} --file <path>\`.`,
       }
     }
-
-    const liveConfig = (live.config ?? live) as Record<string, unknown>
-    const draftConfig = (draft.snapshot.config ?? {}) as Record<string, unknown>
-
-    // Only what the DRAFT declares, and never server-managed bookkeeping.
-    // Taking the union instead reported `createdAt`, `createdBy` and
-    // `currentVersion` as pending changes on a draft that touched none of
-    // them — noise that buries the one field the caller actually staged.
-    const MANAGED = new Set([
-      'id', 'orgId', 'workspaceId', 'createdAt', 'updatedAt', 'createdBy',
-      'currentVersion', 'currentVersionId', 'draft', 'lifecycleStatus',
-    ])
-
-    /**
-     * A snapshot is `config` PLUS fifteen sibling sections, and this compared
-     * only `config`.
-     *
-     * So a draft that staged a capability, a skill, a prompt or a knowledge
-     * attachment reported "matches the live version" — the answer a caller
-     * gets when nothing is pending, given immediately after they staged
-     * something. `capability grant` made this reachable in one step, but
-     * `agent apply` has always been able to stage these sections too.
-     *
-     * The live side comes from the live SNAPSHOT rather than the config row:
-     * `GET /config/agents/:id` returns flat scalars with every relation null,
-     * so every section would read as "changed" against it.
-     */
-    const liveSnapshot = await t.api.agentComposition(t.id).catch(() => null)
-    const draftSections = Object.fromEntries(
-      Object.entries(draft.snapshot).filter(([k]) => k !== 'config' && !MANAGED.has(k)),
-    )
-
-    const changed = [
-      ...Object.keys(draftConfig)
-        .filter((k) => !MANAGED.has(k))
-        .filter((k) => stableStringify(draftConfig[k]) !== stableStringify(liveConfig[k])),
-      // Only when the live snapshot could be read. Reporting every section as
-      // changed because one request failed would be worse than the silence
-      // this replaces.
-      ...(liveSnapshot
-        ? Object.keys(draftSections).filter(
-            (k) => stableStringify(draftSections[k]) !== stableStringify(liveSnapshot[k]),
-          )
-        : []),
-    ].sort()
+    const revision = outcome.revision
 
     return {
-      data: { hasDraft: true, revision: draft.revision, published, changed },
+      data: { hasDraft: true, revision, published, changed },
       text:
         changed.length > 0
-          ? [`Draft revision ${draft.revision} differs in:`, ...changed.map((k) => `  ${k}`)].join('\n')
+          ? [`Draft revision ${revision} differs in:`, ...changed.map((k) => `  ${k}`)].join('\n')
           : published
-            ? `Draft revision ${draft.revision} matches the live version.`
-            : `Draft revision ${draft.revision}. Nothing is published yet, so there is `
+            ? `Draft revision ${revision} matches the live version.`
+            : `Draft revision ${revision}. Nothing is published yet, so there is `
               + 'nothing to compare against — the draft IS the whole configuration.\n'
               + `  Publish it with \`frontera agent publish ${t.ref}\`.`,
     }

package/src/commands/setup.ts

@@ -35,6 +35,14 @@ interface Host {
   bin: string
   /** Verbs differ: Codex `plugin add`, Claude `plugin install`. */
   install: string[]
+  /**
+   * Run after `install` when the host has one. `claude plugin install` is a
+   * no-op on a plugin that is already installed — it does not upgrade — so a
+   * kit newer than what the host holds stayed stale forever, and readiness
+   * kept asking for a setup that changed nothing. `plugin update` is the
+   * upgrade; it is a no-op when already current.
+   */
+  update?: string[]
   marketplaceList: string[]
   installHint: string
 }
@@ -53,6 +61,7 @@ const HOSTS: Record<HostId, Host> = {
     label: 'Claude Code',
     bin: 'claude',
     install: ['plugin', 'install', 'frontera@frontera'],
+    update: ['plugin', 'update', 'frontera@frontera'],
     marketplaceList: ['plugin', 'marketplace', 'list'],
     installHint: 'install Claude Code first — https://claude.com/claude-code',
   },
@@ -207,12 +216,31 @@ export const setupCommand: Command = {
       // upgrade. Not every host has this verb; a failure here is not fatal.
       run(host.bin, ['plugin', 'marketplace', 'update', 'frontera'])
 
-      const installed = run(host.bin, host.install)
+      let installed = run(host.bin, host.install)
+      // Installed is not upgraded: bring an already-present plugin up to the
+      // kit this CLI carries. An update that fails is reported as the failure
+      // it is — readiness would otherwise keep reading the plugin as stale and
+      // keep asking for a setup that "succeeded".
+      if (installed.ok && host.update) {
+        const updated = run(host.bin, host.update)
+        if (!updated.ok) installed = { ...updated, out: `plugin update failed: ${updated.out}` }
+      }
+      // Codex 0.125 dropped `plugin add` (and `plugin list`): plugins are
+      // enabled in its own settings, which this command does not edit. The
+      // marketplace IS registered by now, so say what is left to do rather
+      // than echo the host's usage text.
+      const noVerb = !installed.ok && /unrecognized subcommand/i.test(installed.out)
       results.push({
         host: id,
         installed: installed.ok,
         marketplace: root,
-        ...(installed.ok ? {} : { error: installed.out }),
+        ...(installed.ok
+          ? {}
+          : {
+              error: noVerb
+                ? `${host.label} has no \`${host.install.slice(0, 2).join(' ')}\` — marketplace \`frontera\` is registered; enable the \`frontera\` plugin in ${host.label}'s own plugin settings`
+                : installed.out,
+            }),
       })
     }
 

package/src/forge/claude-adapter.ts

@@ -120,7 +120,7 @@ export class ClaudeAdapter implements HostAdapter {
       // Under bypassPermissions the SDK never consults the callback and warns
       // loudly that it was given one.
       ...(mode === 'bypassPermissions' ? {} : { canUseTool }),
-      env: forgeEnv(),
+      env: forgeEnv(ctx.project.profile ? { FRONTERA_PROFILE: ctx.project.profile } : {}),
       ...(await this.mcpServers(ctx)),
     }
 
@@ -182,8 +182,10 @@ export class ClaudeAdapter implements HostAdapter {
    */
   private async mcpServers(ctx: TurnContext): Promise<Pick<Options, 'mcpServers'>> {
     try {
+      // The project's bound profile outranks the directory walk, the same
+      // way `FRONTERA_PROFILE` does for the commands the host will run.
       const credential = await resolveCredential(
-        ctx.apiUrl ? { apiUrl: ctx.apiUrl } : {},
+        ctx.project.profile ? { profile: ctx.project.profile } : ctx.apiUrl ? { apiUrl: ctx.apiUrl } : {},
         { cwd: ctx.project.root },
       )
       return {

package/src/forge/projects.ts

@@ -8,7 +8,7 @@ import type { ForgeChangeStatus, ForgeChangedFile, ForgeChanges, ForgeFileEntry
 import { findProjectRoot } from '../context'
 import { readProject } from '../project'
 import { applyClaudeImport, applyManagedBlock, type BlockMarkers } from '../kit'
-import { ensureGitignored, findContext, writeContext } from '../project-context'
+import { ensureGitignored, findContext, readContextAt, writeContext } from '../project-context'
 import { listProfiles, normalizeOrigin, type ProfileMetadata } from '../profiles'
 import { badRequest } from './http'
 import type { NewProject } from './store'
@@ -221,7 +221,6 @@ export function workspaceIdInFolder(root: string): string | null {
   }
 }
 
-/** The profile bound to this deployment's API origin, if the CLI has one. */
 /**
  * The profile to bind a workspace folder to.
  *
@@ -283,20 +282,43 @@ export function ensureWorkspaceProject(
   if (!isGitWorkTree(root)) {
     spawnSync('git', ['init', '-q'], { cwd: root, encoding: 'utf8' })
   }
+  let profiles: Array<{ name: string; profile: ProfileMetadata }> = []
+  try {
+    profiles = (deps.profiles ?? listProfiles)()
+  } catch (error) {
+    // `listProfiles` is loud about a corrupt profiles file on purpose; the
+    // daemon must not die for it, but must not hide it either.
+    warn(`could not read CLI profiles: ${error instanceof Error ? error.message : String(error)}`)
+  }
+
+  // This folder's OWN binding first. An ancestor's counts only when it is
+  // this workspace's own key: walking up used to find `~/.frontera/context.json`
+  // for every folder under the home directory, so a managed folder was never
+  // bound and resolved, at run time, to whatever the person had bound their
+  // home to — an organization key `agent list` refuses. A deliberate parent
+  // binding to the right workspace key is honoured; anything else is
+  // overridden here, and the log says so.
   let bound: string | null = null
   try {
-    bound = findContext(root)?.profile ?? null
+    bound = readContextAt(root, process.env)?.profile ?? null
   } catch {
     bound = null
   }
+  let inherited: string | null = null
   if (!bound) {
-    let profiles: Array<{ name: string; profile: ProfileMetadata }> = []
     try {
-      profiles = (deps.profiles ?? listProfiles)()
-    } catch (error) {
-      warn(`could not read CLI profiles: ${error instanceof Error ? error.message : String(error)}`)
+      inherited = findContext(root)?.profile ?? null
+    } catch {
+      inherited = null
     }
+    const inheritedMeta = inherited ? profiles.find((p) => p.name === inherited)?.profile : undefined
+    if (inheritedMeta?.workspaceId === input.workspaceId) bound = inherited
+  }
+  if (!bound) {
     const profile = profileForWorkspace(apiUrl, { workspaceId: input.workspaceId, ...(input.orgId ? { orgId: input.orgId } : {}) }, profiles)
+    if (profile && inherited && inherited !== profile) {
+      warn(`${root}: binding to \`${profile}\` (this workspace's key); an ancestor binds \`${inherited}\`, which is not`)
+    }
     if (!profile) {
       warn(`no CLI profile for this workspace or organization at ${apiUrl ?? '(no api url)'}; ${root} left unbound`)
     } else {

package/src/forge/runs.ts

@@ -6,6 +6,8 @@ import { readUIMessageStream, type UIMessage, type UIMessageChunk } from 'ai'
 import type { AdapterFactory, ApprovalDecision, HostAdapter } from './adapter'
 import type { Logger } from './log'
 import type { ForgeStore, StoredThread } from './store'
+import { enrichTouch, touchDelta, type TouchEnricher } from './touch-details'
+import { TouchTracker } from './touches'
 
 /**
  * Live turns. Each run keeps an append-only chunk journal in memory and fans
@@ -82,6 +84,8 @@ export class RunManager {
     private readonly adapters: AdapterFactory,
     private readonly log: Logger,
     private readonly apiUrl: string,
+    /** Injectable so a test can script what a touch turns out to have changed. */
+    private readonly enrich: TouchEnricher = enrichTouch,
   ) {}
 
   activeRunFor(threadId: string): string | null {
@@ -186,10 +190,49 @@ export class RunManager {
   }
 
   private async execute(run: LiveRun, thread: StoredThread, project: ForgeProject, text: string): Promise<void> {
+    // Watches the same chunks the client sees for `frontera` commands that
+    // succeeded, and writes each as a touch as it happens — the pane polls
+    // the store for them, and a reload could not rebuild them from messages.
+    const touches = new TouchTracker()
+    // Enrichments run one after another: two touches from one command line
+    // (`apply a && capability grant a x`) must not race, or the later one's
+    // delta is computed before the earlier has its details and blames the
+    // whole pending draft on itself.
+    let enrichments: Promise<void> = Promise.resolve()
     const emit = (chunk: UIMessageChunk) => {
       if (run.finished) return
       run.journal.push(chunk)
       for (const sub of run.subscribers) sub.push(chunk)
+      for (const touch of touches.observe(chunk)) {
+        try {
+          if (this.store.getThread(thread.id)) {
+            const stored = this.store.insertTouch({ threadId: thread.id, runId: run.id, ...touch })
+            // Off the emit path: the answer needs the platform, and the turn
+            // must not wait for it. Nothing here can fail the run.
+            enrichments = enrichments.then(() => this.enrich(touch, project))
+              .then((details) => {
+                if (!details) return
+                // Against the last enriched touch on the same agent before
+                // this one, so the pane points at what THIS touch changed,
+                // not at the whole pending draft.
+                const previous = this.store.previousEnrichedAgentTouch(thread.id, stored.id, {
+                  ref: touch.ref,
+                  ...(details.label ? { label: details.label } : {}),
+                })
+                this.store.updateTouchDetails(stored.id, {
+                  ...details,
+                  delta: touchDelta(details.changed, previous?.details),
+                })
+              })
+              .catch((err) => {
+                this.log.warn(`run ${run.id}: touch ${stored.id} not enriched: ${err instanceof Error ? err.message : String(err)}`)
+              })
+          }
+        } catch (err) {
+          // A lost touch degrades the pane, never the turn.
+          this.log.warn(`run ${run.id}: touch not recorded: ${err instanceof Error ? err.message : String(err)}`)
+        }
+      }
     }
 
     let outcome: { error: string | null }

package/src/forge/server.ts

@@ -31,6 +31,7 @@ import { skillsFor } from './claude-skills'
 import { normalizeTurnText } from './turn-text'
 import { ensureWorkspaceProject, inspectRoot, listFiles, readChanges, resolveWorkspaceRoot, workspaceIdInFolder } from './projects'
 import { RunManager } from './runs'
+import type { TouchEnricher } from './touch-details'
 import { sessionView } from './sessions'
 import { ForgeStore, type StoredThread, type ThreadPatch } from './store'
 import { TerminalManager, type TerminalClient } from './terminals'
@@ -56,6 +57,8 @@ export interface ForgeServerOptions {
   storePath: string
   log: Logger
   adapters?: AdapterFactory
+  /** How a recorded touch learns what it changed. A test scripts it. */
+  touchEnricher?: TouchEnricher
   /**
    * Where managed workspace folders are created. Defaults to `~/Frontera`; a
    * test points it at a scratch directory so it never touches the real one.
@@ -193,7 +196,7 @@ export function startForgeServer(opts: ForgeServerOptions): ForgeServer {
   const store = new ForgeStore(opts.storePath)
   const reaped = store.reapOrphanRuns()
   if (reaped > 0) log.warn(`${reaped} run(s) from a previous daemon marked interrupted`)
-  const runs = new RunManager(store, opts.adapters ?? defaultAdapters(log), log, opts.apiUrl)
+  const runs = new RunManager(store, opts.adapters ?? defaultAdapters(log), log, opts.apiUrl, opts.touchEnricher)
   const terminals = new TerminalManager(log)
 
   const corsHeaders = (): Record<string, string> =>
@@ -393,6 +396,12 @@ export function startForgeServer(opts: ForgeServerOptions): ForgeServer {
   }
   route('DELETE', '/v1/forge/threads/:id', (_req, params) => deleteThread(params.id!))
 
+  // What the session changed on the platform, for the preview pane to follow.
+  route('GET', '/v1/forge/threads/:id/touches', (_req, params) => {
+    requireThread(params.id!)
+    return ok(store.listTouches(params.id!))
+  })
+
   // -- terminals ------------------------------------------------------------
 
   // `?threadId=` is how the surface lists one session's tabs; unfiltered is

package/src/forge/store.ts

@@ -2,7 +2,15 @@ import { Database } from 'bun:sqlite'
 import { mkdirSync } from 'node:fs'
 import { dirname } from 'node:path'
 
-import type { ForgeHostId, ForgeProject, ForgeThread, ForgeThreadStatus } from '@frontera-sdk/forge-contracts'
+import type {
+  ForgeArtifactKind,
+  ForgeArtifactTouch,
+  ForgeArtifactTouchDetails,
+  ForgeHostId,
+  ForgeProject,
+  ForgeThread,
+  ForgeThreadStatus,
+} from '@frontera-sdk/forge-contracts'
 import type { UIMessage } from 'ai'
 
 /**
@@ -57,6 +65,19 @@ CREATE TABLE IF NOT EXISTS runs (
   finished_at TEXT,
   error TEXT
 );
+CREATE TABLE IF NOT EXISTS touches (
+  id TEXT PRIMARY KEY,
+  thread_id TEXT NOT NULL,
+  run_id TEXT NOT NULL,
+  seq INTEGER NOT NULL,
+  kind TEXT NOT NULL,
+  verb TEXT NOT NULL,
+  ref TEXT,
+  live INTEGER NOT NULL DEFAULT 0,
+  at TEXT NOT NULL,
+  details TEXT
+);
+CREATE INDEX IF NOT EXISTS touches_thread ON touches(thread_id, seq);
 `
 
 interface ProjectRow {
@@ -104,6 +125,28 @@ interface RunRow {
   error: string | null
 }
 
+interface TouchRow {
+  id: string
+  thread_id: string
+  run_id: string
+  seq: number
+  kind: string
+  verb: string
+  ref: string | null
+  live: number
+  at: string
+  details: string | null
+}
+
+export interface NewTouch {
+  threadId: string
+  runId: string
+  kind: ForgeArtifactKind
+  verb: string
+  ref: string | null
+  live: boolean
+}
+
 /** A thread as stored: the wire shape plus the archive flag sessions expose. */
 export interface StoredThread extends ForgeThread {
   archived: boolean
@@ -206,6 +249,20 @@ function runFromRow(row: RunRow): StoredRun {
   }
 }
 
+function touchFromRow(row: TouchRow): ForgeArtifactTouch {
+  return {
+    id: row.id,
+    threadId: row.thread_id,
+    runId: row.run_id,
+    kind: row.kind as ForgeArtifactKind,
+    verb: row.verb,
+    ref: row.ref,
+    live: row.live === 1,
+    at: row.at,
+    details: row.details ? (JSON.parse(row.details) as ForgeArtifactTouchDetails) : null,
+  }
+}
+
 export class ForgeStore {
   private readonly db: Database
   /** A store from before host-native modes still carries a NOT NULL column. */
@@ -382,9 +439,64 @@ export class ForgeStore {
   deleteThread(id: string): void {
     this.db.query('DELETE FROM messages WHERE thread_id = ?').run(id)
     this.db.query('DELETE FROM runs WHERE thread_id = ?').run(id)
+    this.db.query('DELETE FROM touches WHERE thread_id = ?').run(id)
     this.db.query('DELETE FROM threads WHERE id = ?').run(id)
   }
 
+  // -- touches --------------------------------------------------------------
+
+  /**
+   * Oldest first: the pane walks this as history, and "the latest" is the
+   * last row. `seq` orders rather than `at`, so two touches from one command
+   * line (`frontera agent apply a && frontera agent publish a`) keep the
+   * order the shell ran them in even inside the same millisecond.
+   */
+  listTouches(threadId: string): ForgeArtifactTouch[] {
+    return this.db
+      .query<TouchRow, [string]>('SELECT * FROM touches WHERE thread_id = ? ORDER BY seq ASC')
+      .all(threadId)
+      .map(touchFromRow)
+  }
+
+  insertTouch(input: NewTouch): ForgeArtifactTouch {
+    const last = this.db
+      .query<{ seq: number | null }, [string]>('SELECT MAX(seq) AS seq FROM touches WHERE thread_id = ?')
+      .get(input.threadId)
+    const seq = (last?.seq ?? -1) + 1
+    const id = crypto.randomUUID()
+    this.db
+      .query('INSERT INTO touches (id, thread_id, run_id, seq, kind, verb, ref, live, at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)')
+      .run(id, input.threadId, input.runId, seq, input.kind, input.verb, input.ref, input.live ? 1 : 0, now())
+    const row = this.db.query<TouchRow, [string]>('SELECT * FROM touches WHERE id = ?').get(id)
+    return touchFromRow(row!)
+  }
+
+  /**
+   * The last touch on the same agent, BEFORE this one in the thread, that
+   * already carries details — what a delta is computed against. "Same agent"
+   * is the same ref, or the same resolved name: the CLI addresses by slug and
+   * MCP by uuid. Before, not merely other: two touches from one command line
+   * enrich concurrently, and the earlier must not diff against the later.
+   */
+  previousEnrichedAgentTouch(threadId: string, touchId: string, match: { ref: string | null; label?: string }): ForgeArtifactTouch | null {
+    const row = this.db
+      .query<TouchRow, [string, string, string | null, string | null]>(
+        `SELECT * FROM touches WHERE thread_id = ? AND kind = 'agent' AND details IS NOT NULL
+           AND seq < (SELECT seq FROM touches WHERE id = ?)
+           AND (ref = ? OR json_extract(details, '$.label') = ?)
+         ORDER BY seq DESC LIMIT 1`,
+      )
+      .get(threadId, touchId, match.ref, match.label ?? null)
+    return row ? touchFromRow(row) : null
+  }
+
+  /** Fills in what the enricher found; a touch deleted meanwhile is a no-op. */
+  updateTouchDetails(id: string, details: ForgeArtifactTouchDetails): ForgeArtifactTouch | null {
+    this.db.query('UPDATE touches SET details = ? WHERE id = ?').run(JSON.stringify(details), id)
+    const row = this.db.query<TouchRow, [string]>('SELECT * FROM touches WHERE id = ?').get(id)
+    return row ? touchFromRow(row) : null
+  }
+
   // -- messages -------------------------------------------------------------
 
   listMessages(threadId: string): UIMessage[] {

package/src/forge/terminals.ts

@@ -99,7 +99,11 @@ export class TerminalManager {
     try {
       proc = Bun.spawn([shell, '-l'], {
         cwd: project.root,
-        env: forgeEnv({ TERM: 'xterm-256color', COLORTERM: 'truecolor' }),
+        env: forgeEnv({
+          TERM: 'xterm-256color',
+          COLORTERM: 'truecolor',
+          ...(project.profile ? { FRONTERA_PROFILE: project.profile } : {}),
+        }),
         terminal: {
           cols,
           rows,