@akira-tl/forgerelay 0.4.7 → 0.5.1

package/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.5.1] - 2026-08-14
+
+### Added
+
+- Routed ForgeRelay's top-level work operations through one persistent Activity lifecycle: read, write, edit, rename, delete, capability, Bash, and Codex-compatible execution/patch operations now record durable started/succeeded/failed/blocked/returned facts without relying on UI inference. Bash/exec process-control follow-ups remain part of the existing semantic operation instead of creating duplicate top-level Activities.
+
+### Fixed
+
+- Activity auditing now treats a shell process as `returned` only after its `processId` can actually be delivered to the Host; Host cancellation during post-tool delivery protection records a failed Activity and discards the undelivered process instead of leaving a false returned history entry.
+
+## [0.5.0] - 2026-08-14
+
+### Added
+
+- Added the production local Activity audit foundation: append-only Audit Events persist in ForgeRelay's existing SQLite state, queryable Activity Records survive server restarts and Workspace cleanup, and success, failure, and Hook-blocked outcomes retain immutable Workspace/Host Turn execution context for later lifecycle and UI releases.
+
 ## [0.4.7] - 2026-08-11
 
 ### Added

package/dist/activity/audit-store.js

@@ -0,0 +1,220 @@
+import { randomUUID } from "node:crypto";
+import { openDatabase } from "../db/client.js";
+export class ActivityAuditStore {
+    database;
+    now;
+    constructor(stateDir, options = {}) {
+        this.database = openDatabase(stateDir);
+        this.now = options.now ?? (() => new Date());
+    }
+    append(input) {
+        return this.database.sqlite.transaction(() => {
+            const existing = this.readRows(input.activityId);
+            if (input.type === "started") {
+                if (existing.length > 0) {
+                    throw new Error(`Activity ${input.activityId} already has audit events.`);
+                }
+            }
+            else if (existing.length === 0 || existing[0]?.event_type !== "started") {
+                throw new Error(`Activity ${input.activityId} must start before recording ${input.type}.`);
+            }
+            const sequence = existing.length + 1;
+            const id = `evt_${randomUUID().replaceAll("-", "")}`;
+            const createdAt = this.now().toISOString();
+            const row = eventInputToRow(input, { id, sequence, createdAt });
+            this.database.sqlite.prepare(`insert into activity_audit_events (
+          id,
+          activity_id,
+          sequence,
+          event_type,
+          turn_id,
+          conversation_scope_id,
+          tool,
+          workspace_id,
+          workspace_root,
+          workspace_mode,
+          workspace_source_root,
+          workspace_branch,
+          workspace_target_branch,
+          request_json,
+          result_json,
+          error,
+          created_at
+        ) values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(row.id, row.activity_id, row.sequence, row.event_type, row.turn_id, row.conversation_scope_id, row.tool, row.workspace_id, row.workspace_root, row.workspace_mode, row.workspace_source_root, row.workspace_branch, row.workspace_target_branch, row.request_json, row.result_json, row.error, row.created_at);
+            return rowToEvent(row);
+        })();
+    }
+    listEvents(activityId) {
+        return this.readRows(activityId).map(rowToEvent);
+    }
+    getActivity(activityId) {
+        const events = this.listEvents(activityId);
+        const started = events[0];
+        if (!started || started.type !== "started")
+            return undefined;
+        let state = "executing";
+        let result;
+        let error;
+        let updatedAt = started.createdAt;
+        for (const event of events.slice(1)) {
+            updatedAt = event.createdAt;
+            switch (event.type) {
+                case "started":
+                    break;
+                case "succeeded":
+                    state = "done";
+                    result = event.result;
+                    error = undefined;
+                    break;
+                case "returned":
+                    state = "returned";
+                    result = event.result;
+                    error = undefined;
+                    break;
+                case "failed":
+                    state = "failed";
+                    result = event.result;
+                    error = event.error;
+                    break;
+                case "blocked":
+                    state = "blocked";
+                    result = undefined;
+                    error = event.error;
+                    break;
+            }
+        }
+        return {
+            activityId: started.activityId,
+            turnId: started.turnId,
+            ...(started.conversationScopeId ? { conversationScopeId: started.conversationScopeId } : {}),
+            tool: started.tool,
+            workspace: started.workspace,
+            state,
+            ...(started.request !== undefined ? { request: started.request } : {}),
+            ...(result !== undefined ? { result } : {}),
+            ...(error !== undefined ? { error } : {}),
+            startedAt: started.createdAt,
+            updatedAt,
+        };
+    }
+    close() {
+        this.database.close();
+    }
+    readRows(activityId) {
+        return this.database.sqlite.prepare(`select * from activity_audit_events
+       where activity_id = ?
+       order by sequence asc`).all(activityId);
+    }
+}
+function eventInputToRow(input, identity) {
+    if (input.type === "started") {
+        return {
+            id: identity.id,
+            activity_id: input.activityId,
+            sequence: identity.sequence,
+            event_type: input.type,
+            turn_id: input.turnId,
+            conversation_scope_id: input.conversationScopeId ?? null,
+            tool: input.tool,
+            workspace_id: input.workspace.id ?? null,
+            workspace_root: input.workspace.root,
+            workspace_mode: input.workspace.mode,
+            workspace_source_root: input.workspace.sourceRoot ?? null,
+            workspace_branch: input.workspace.branch ?? null,
+            workspace_target_branch: input.workspace.targetBranch ?? null,
+            request_json: serializeJson(input.request),
+            result_json: null,
+            error: null,
+            created_at: identity.createdAt,
+        };
+    }
+    return {
+        id: identity.id,
+        activity_id: input.activityId,
+        sequence: identity.sequence,
+        event_type: input.type,
+        turn_id: null,
+        conversation_scope_id: null,
+        tool: null,
+        workspace_id: null,
+        workspace_root: null,
+        workspace_mode: null,
+        workspace_source_root: null,
+        workspace_branch: null,
+        workspace_target_branch: null,
+        request_json: null,
+        result_json: "result" in input ? serializeJson(input.result) : null,
+        error: "error" in input ? input.error : null,
+        created_at: identity.createdAt,
+    };
+}
+function rowToEvent(row) {
+    const base = {
+        id: row.id,
+        activityId: row.activity_id,
+        sequence: row.sequence,
+        createdAt: row.created_at,
+    };
+    switch (row.event_type) {
+        case "started":
+            if (!row.turn_id || !row.tool || !row.workspace_root || !isWorkspaceMode(row.workspace_mode)) {
+                throw new Error(`Activity audit start event ${row.id} is missing required context.`);
+            }
+            return {
+                ...base,
+                type: "started",
+                turnId: row.turn_id,
+                ...(row.conversation_scope_id ? { conversationScopeId: row.conversation_scope_id } : {}),
+                tool: row.tool,
+                workspace: {
+                    ...(row.workspace_id ? { id: row.workspace_id } : {}),
+                    root: row.workspace_root,
+                    mode: row.workspace_mode,
+                    ...(row.workspace_source_root ? { sourceRoot: row.workspace_source_root } : {}),
+                    ...(row.workspace_branch ? { branch: row.workspace_branch } : {}),
+                    ...(row.workspace_target_branch ? { targetBranch: row.workspace_target_branch } : {}),
+                },
+                ...(row.request_json !== null ? { request: parseJson(row.request_json) } : {}),
+            };
+        case "succeeded":
+            return {
+                ...base,
+                type: "succeeded",
+                result: parseJson(row.result_json),
+            };
+        case "returned":
+            return {
+                ...base,
+                type: "returned",
+                result: parseJson(row.result_json),
+            };
+        case "failed":
+            if (!row.error)
+                throw new Error(`Activity audit failed event ${row.id} is missing an error.`);
+            return {
+                ...base,
+                type: "failed",
+                result: parseJson(row.result_json),
+                error: row.error,
+            };
+        case "blocked":
+            if (!row.error)
+                throw new Error(`Activity audit blocked event ${row.id} is missing an error.`);
+            return {
+                ...base,
+                type: "blocked",
+                error: row.error,
+            };
+        default:
+            throw new Error(`Unknown Activity audit event type: ${row.event_type}`);
+    }
+}
+function isWorkspaceMode(value) {
+    return value === "checkout" || value === "worktree";
+}
+function serializeJson(value) {
+    return value === undefined ? null : JSON.stringify(value);
+}
+function parseJson(value) {
+    return value === null ? undefined : JSON.parse(value);
+}

package/dist/activity/lifecycle.js

@@ -0,0 +1,111 @@
+import { randomUUID } from "node:crypto";
+import { HookExecutionError } from "../hooks.js";
+export class ActivityLifecycle {
+    auditStore;
+    activityId;
+    turnId;
+    constructor(auditStore, options = {}) {
+        this.auditStore = auditStore;
+        this.activityId = options.activityId ?? newActivityId;
+        this.turnId = options.turnId ?? newTurnId;
+    }
+    async run(options) {
+        const activityId = options.activityId ?? this.activityId();
+        const turnId = options.turnId ?? this.turnId();
+        const request = normalizeAuditValue(options.request);
+        this.auditStore.append({
+            type: "started",
+            activityId,
+            turnId,
+            ...(options.conversationScopeId ? { conversationScopeId: options.conversationScopeId } : {}),
+            tool: options.tool,
+            workspace: options.workspace,
+            ...(request !== undefined ? { request } : {}),
+        });
+        try {
+            const result = await options.operation();
+            const normalizedResult = normalizeAuditValue(result);
+            const outcome = options.outcome?.(result) ?? { type: "succeeded" };
+            switch (outcome.type) {
+                case "succeeded":
+                case "returned":
+                    this.auditStore.append({
+                        type: outcome.type,
+                        activityId,
+                        ...(normalizedResult !== undefined ? { result: normalizedResult } : {}),
+                    });
+                    break;
+                case "failed":
+                    this.auditStore.append({
+                        type: "failed",
+                        activityId,
+                        ...(normalizedResult !== undefined ? { result: normalizedResult } : {}),
+                        error: outcome.error,
+                    });
+                    break;
+            }
+            return result;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.auditStore.append(error instanceof HookExecutionError && error.event === "BeforeTool"
+                ? { type: "blocked", activityId, error: message }
+                : { type: "failed", activityId, error: message });
+            throw error;
+        }
+    }
+}
+function newActivityId() {
+    return `act_${randomUUID().replaceAll("-", "")}`;
+}
+function newTurnId() {
+    return `turn_${randomUUID().replaceAll("-", "")}`;
+}
+export function normalizeAuditValue(value) {
+    return normalizeAuditValueInternal(value, new WeakSet());
+}
+function normalizeAuditValueInternal(value, seen) {
+    if (value === undefined || typeof value === "function" || typeof value === "symbol")
+        return undefined;
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : String(value);
+    if (typeof value === "bigint")
+        return value.toString();
+    if (value instanceof Date)
+        return value.toISOString();
+    if (value instanceof Error) {
+        return {
+            name: value.name,
+            message: value.message,
+        };
+    }
+    if (value instanceof Uint8Array) {
+        return {
+            type: "bytes",
+            encoding: "base64",
+            data: Buffer.from(value).toString("base64"),
+        };
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry) => normalizeAuditValueInternal(entry, seen) ?? null);
+    }
+    if (typeof value !== "object")
+        return String(value);
+    if (seen.has(value))
+        return "[Circular]";
+    seen.add(value);
+    try {
+        const normalized = {};
+        for (const [key, entry] of Object.entries(value)) {
+            const next = normalizeAuditValueInternal(entry, seen);
+            if (next !== undefined)
+                normalized[key] = next;
+        }
+        return normalized;
+    }
+    finally {
+        seen.delete(value);
+    }
+}

package/dist/db/migrations.js

@@ -34,6 +34,11 @@ const migrations = [
         name: "workspace-context-deliveries",
         up: migrateWorkspaceContextDeliveries,
     },
+    {
+        version: 8,
+        name: "activity-audit",
+        up: migrateActivityAudit,
+    },
 ];
 export function migrateDatabase(sqlite) {
     const migrate = sqlite.transaction(() => {
@@ -208,6 +213,41 @@ function migrateWorkspaceContextDeliveries(sqlite) {
       on workspace_context_deliveries(delivered_at desc);
   `);
 }
+function migrateActivityAudit(sqlite) {
+    sqlite.exec(`
+    create table if not exists activity_audit_events (
+      id text primary key,
+      activity_id text not null,
+      sequence integer not null,
+      event_type text not null,
+      turn_id text,
+      conversation_scope_id text,
+      tool text,
+      workspace_id text,
+      workspace_root text,
+      workspace_mode text,
+      workspace_source_root text,
+      workspace_branch text,
+      workspace_target_branch text,
+      request_json text,
+      result_json text,
+      error text,
+      created_at text not null
+    );
+
+    create unique index if not exists activity_audit_events_activity_sequence_unique_idx
+      on activity_audit_events(activity_id, sequence);
+
+    create index if not exists activity_audit_events_activity_idx
+      on activity_audit_events(activity_id, sequence);
+
+    create index if not exists activity_audit_events_turn_idx
+      on activity_audit_events(turn_id, created_at);
+
+    create index if not exists activity_audit_events_created_idx
+      on activity_audit_events(created_at);
+  `);
+}
 function addColumnIfMissing(sqlite, table, column, definition) {
     const columns = sqlite.prepare(`pragma table_info(${table})`).all();
     if (columns.some((existingColumn) => existingColumn.name === column))

package/dist/db/schema.js

@@ -1,4 +1,4 @@
-import { index, integer, primaryKey, sqliteTable, text } from "drizzle-orm/sqlite-core";
+import { index, integer, primaryKey, sqliteTable, text, uniqueIndex } from "drizzle-orm/sqlite-core";
 export const workspaceSessions = sqliteTable("workspace_sessions", {
     id: text("id").primaryKey(),
     root: text("root").notNull(),
@@ -73,6 +73,30 @@ export const oauthRefreshTokens = sqliteTable("oauth_refresh_tokens", {
     expiresAt: integer("expires_at").notNull(),
     resource: text("resource"),
 });
+export const activityAuditEvents = sqliteTable("activity_audit_events", {
+    id: text("id").primaryKey(),
+    activityId: text("activity_id").notNull(),
+    sequence: integer("sequence").notNull(),
+    eventType: text("event_type").notNull(),
+    turnId: text("turn_id"),
+    conversationScopeId: text("conversation_scope_id"),
+    tool: text("tool"),
+    workspaceId: text("workspace_id"),
+    workspaceRoot: text("workspace_root"),
+    workspaceMode: text("workspace_mode"),
+    workspaceSourceRoot: text("workspace_source_root"),
+    workspaceBranch: text("workspace_branch"),
+    workspaceTargetBranch: text("workspace_target_branch"),
+    requestJson: text("request_json"),
+    resultJson: text("result_json"),
+    error: text("error"),
+    createdAt: text("created_at").notNull(),
+}, (table) => [
+    uniqueIndex("activity_audit_events_activity_sequence_unique_idx").on(table.activityId, table.sequence),
+    index("activity_audit_events_activity_idx").on(table.activityId, table.sequence),
+    index("activity_audit_events_turn_idx").on(table.turnId, table.createdAt),
+    index("activity_audit_events_created_idx").on(table.createdAt),
+]);
 export const localAgentSessions = sqliteTable("local_agent_sessions", {
     id: text("id").primaryKey(),
     workspaceId: text("workspace_id"),

package/dist/lsp/test-support/server-fixture.js

@@ -4,6 +4,8 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { ActivityAuditStore } from "../../activity/audit-store.js";
+import { ActivityLifecycle } from "../../activity/lifecycle.js";
 import { loadConfig } from "../../config.js";
 import { createReviewCheckpointManager } from "../../review-checkpoints.js";
 import { ProcessManager } from "../../process-sessions.js";
@@ -33,8 +35,10 @@ export async function createCodeIntelligenceServerFixture(t, options = {}) {
     const store = new SqliteWorkspaceStore(stateDir);
     const workspaces = new WorkspaceRegistry(config, store);
     const processSessions = new ProcessManager();
+    const auditStore = new ActivityAuditStore(stateDir);
+    const activityLifecycle = new ActivityLifecycle(auditStore);
     const codeIntelligence = new CodeIntelligenceManager(config, options.codeIntelligenceOptions);
-    const server = createMcpServer(config, workspaces, createReviewCheckpointManager(), processSessions, [], [], codeIntelligence);
+    const server = createMcpServer(config, workspaces, createReviewCheckpointManager(), processSessions, [], [], codeIntelligence, activityLifecycle);
     const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
     const client = new Client({ name: "forgerelay-code-intelligence-test-client", version: "1.0.0" });
     await Promise.all([client.connect(clientTransport), server.connect(serverTransport)]);
@@ -47,6 +51,7 @@ export async function createCodeIntelligenceServerFixture(t, options = {}) {
         await server.close();
         await codeIntelligence.shutdown();
         processSessions.shutdown();
+        auditStore.close();
         store.close();
     };
     t.after(async () => {

package/dist/server.js

@@ -15,6 +15,8 @@ import { registerAppResource, registerAppTool, RESOURCE_MIME_TYPE, } from "@mode
 import express from "express";
 import * as z from "zod/v4";
 import { applyPatch } from "./apply-patch.js";
+import { ActivityAuditStore } from "./activity/audit-store.js";
+import { ActivityLifecycle } from "./activity/lifecycle.js";
 import { buildCapabilityFingerprint } from "./capabilities.js";
 import { CapabilityError, createCapabilityRegistry, } from "./capability-registry.js";
 import { deletePath, renamePath } from "./file-mutations.js";
@@ -597,7 +599,77 @@ async function reviewWorkspaceChanges(reviewCheckpoints, workspace) {
 function toolResultIsError(result) {
     return typeof result === "object" && result !== null && result.isError === true;
 }
-function registerProcessTools(server, config, workspaces, processSessions, hooks) {
+function workspaceActivitySnapshot(workspace) {
+    return {
+        id: workspace.id,
+        root: workspace.root,
+        mode: workspace.mode,
+        ...(workspace.sourceRoot ? { sourceRoot: workspace.sourceRoot } : {}),
+        ...(workspace.worktree?.branch ? { branch: workspace.worktree.branch } : {}),
+        ...(workspace.worktree?.targetBranch ? { targetBranch: workspace.worktree.targetBranch } : {}),
+    };
+}
+function activityFailureMessage(result) {
+    if (typeof result !== "object" || result === null)
+        return "Tool returned a failed result.";
+    const record = result;
+    if (Array.isArray(record.content)) {
+        const text = record.content
+            .map((entry) => {
+            if (typeof entry !== "object" || entry === null)
+                return "";
+            const value = entry.text;
+            return typeof value === "string" ? value : "";
+        })
+            .filter(Boolean)
+            .join("\n");
+        if (text)
+            return text;
+    }
+    if (typeof record.structuredContent === "object" && record.structuredContent !== null) {
+        const value = record.structuredContent.result;
+        if (typeof value === "string" && value)
+            return value;
+    }
+    return "Tool returned a failed result.";
+}
+function standardActivityOutcome(result) {
+    return toolResultIsError(result)
+        ? { type: "failed", error: activityFailureMessage(result) }
+        : { type: "succeeded" };
+}
+function processActivityOutcome(result) {
+    if (toolResultIsError(result))
+        return { type: "failed", error: activityFailureMessage(result) };
+    if (typeof result !== "object" || result === null)
+        return { type: "succeeded" };
+    const structured = result.structuredContent;
+    if (typeof structured !== "object" || structured === null)
+        return { type: "succeeded" };
+    const process = structured;
+    if (process.running === true)
+        return { type: "returned" };
+    if (process.timedOut === true ||
+        typeof process.signal === "string" ||
+        (typeof process.exitCode === "number" && process.exitCode !== 0)) {
+        return { type: "failed", error: activityFailureMessage(result) };
+    }
+    return { type: "succeeded" };
+}
+function runActivityTool(lifecycle, workspace, requestMeta, tool, request, operation, outcome = standardActivityOutcome) {
+    return lifecycle.run({
+        tool,
+        workspace: workspaceActivitySnapshot(workspace),
+        conversationScopeId: openAiConversationScopeId(requestMeta),
+        request,
+        operation,
+        outcome,
+    });
+}
+function runActivityToolWithHooks(lifecycle, hooks, workspace, requestMeta, request, hookOptions) {
+    return runActivityTool(lifecycle, workspace, requestMeta, hookOptions.tool, request, () => runToolWithHooks(hooks, hookOptions));
+}
+function registerProcessTools(server, config, workspaces, processSessions, hooks, activityLifecycle) {
     if (config.toolMode === "codex") {
         registerAppTool(server, "exec_command", {
             title: "Execute command",
@@ -643,61 +715,63 @@ function registerProcessTools(server, config, workspaces, processSessions, hooks
         }, async ({ workspaceId, cmd, tty, columns, rows, workingDirectory, yieldTimeMs, timeoutMs, maxOutputTokens }, extra) => {
             const workspace = workspaces.getWorkspace(workspaceId);
             let undeliveredProcessId;
-            try {
-                const result = await runToolWithHooks(hooks, {
-                    signal: extra.signal,
-                    tool: "exec_command",
-                    invocation: workspaceHookInvocation(workspace),
-                    payload: { command: cmd, workingDirectory: workingDirectory ?? "." },
-                    operation: async () => {
-                        const startedAt = performance.now();
-                        const cwd = workspaces.resolveWorkingDirectory(workspace, workingDirectory);
-                        await assertWorkspaceInstructionsLoadedBeforeSideEffect(workspaces, workspace, [cwd]);
-                        const snapshot = await processSessions.start({
-                            workspaceId,
-                            command: cmd,
-                            cwd,
-                            workspaceRoot: workspace.root,
-                            tty,
-                            columns,
-                            rows,
-                            yieldTimeMs,
-                            timeoutMs,
-                            maxOutputTokens,
-                            codexCi: true,
-                            signal: extra.signal,
-                        });
-                        undeliveredProcessId = snapshot.running ? snapshot.processId : undefined;
-                        logToolCall(config, {
-                            tool: "exec_command",
-                            ...workspaceLogContext(workspace, extra.sessionId),
-                            workingDirectory: workingDirectory ?? ".",
-                            command: cmd,
-                            commandLength: cmd.length,
-                            exitCode: snapshot.exitCode,
-                            running: snapshot.running,
-                            processId: snapshot.processId,
-                            success: snapshot.running || snapshot.exitCode === 0,
-                            durationMs: Math.round(performance.now() - startedAt),
-                        });
-                        return processToolResponse("exec_command", workspaceId, snapshot, {
-                            command: cmd,
-                            workingDirectory: workingDirectory ?? ".",
-                            running: snapshot.running,
-                            exitCode: snapshot.exitCode,
-                            wallTimeMs: snapshot.wallTimeMs,
-                        });
-                    },
-                });
-                extra.signal.throwIfAborted();
-                return result;
-            }
-            catch (error) {
-                if (undeliveredProcessId !== undefined) {
-                    processSessions.discardUndelivered(workspaceId, undeliveredProcessId);
+            return runActivityTool(activityLifecycle, workspace, extra._meta, "exec_command", { workspaceId, cmd, tty, columns, rows, workingDirectory, yieldTimeMs, timeoutMs, maxOutputTokens }, async () => {
+                try {
+                    const result = await runToolWithHooks(hooks, {
+                        signal: extra.signal,
+                        tool: "exec_command",
+                        invocation: workspaceHookInvocation(workspace),
+                        payload: { command: cmd, workingDirectory: workingDirectory ?? "." },
+                        operation: async () => {
+                            const startedAt = performance.now();
+                            const cwd = workspaces.resolveWorkingDirectory(workspace, workingDirectory);
+                            await assertWorkspaceInstructionsLoadedBeforeSideEffect(workspaces, workspace, [cwd]);
+                            const snapshot = await processSessions.start({
+                                workspaceId,
+                                command: cmd,
+                                cwd,
+                                workspaceRoot: workspace.root,
+                                tty,
+                                columns,
+                                rows,
+                                yieldTimeMs,
+                                timeoutMs,
+                                maxOutputTokens,
+                                codexCi: true,
+                                signal: extra.signal,
+                            });
+                            undeliveredProcessId = snapshot.running ? snapshot.processId : undefined;
+                            logToolCall(config, {
+                                tool: "exec_command",
+                                ...workspaceLogContext(workspace, extra.sessionId),
+                                workingDirectory: workingDirectory ?? ".",
+                                command: cmd,
+                                commandLength: cmd.length,
+                                exitCode: snapshot.exitCode,
+                                running: snapshot.running,
+                                processId: snapshot.processId,
+                                success: snapshot.running || snapshot.exitCode === 0,
+                                durationMs: Math.round(performance.now() - startedAt),
+                            });
+                            return processToolResponse("exec_command", workspaceId, snapshot, {
+                                command: cmd,
+                                workingDirectory: workingDirectory ?? ".",
+                                running: snapshot.running,
+                                exitCode: snapshot.exitCode,
+                                wallTimeMs: snapshot.wallTimeMs,
+                            });
+                        },
+                    });
+                    extra.signal.throwIfAborted();
+                    return result;
                 }
-                throw error;
-            }
+                catch (error) {
+                    if (undeliveredProcessId !== undefined) {
+                        processSessions.discardUndelivered(workspaceId, undeliveredProcessId);
+                    }
+                    throw error;
+                }
+            }, processActivityOutcome);
         });
     }
     if (config.toolMode !== "codex")
@@ -775,7 +849,7 @@ function registerProcessTools(server, config, workspaces, processSessions, hooks
         });
     });
 }
-export function createMcpServer(config, workspaces, reviewCheckpoints, processSessions, localAgentProviders, incomingArtifactAdapters, codeIntelligence) {
+export function createMcpServer(config, workspaces, reviewCheckpoints, processSessions, localAgentProviders, incomingArtifactAdapters, codeIntelligence, activityLifecycle) {
     const toolDescriptions = buildToolDescriptions(config);
     const hooks = new HookRunner(config.hooks, config.logging, process.env, (workspaceId, result) => attachCompletedProcessNotices(processSessions, workspaceId, result));
     const incomingArtifactRegistry = new IncomingArtifactAdapterRegistry(incomingArtifactAdapters);
@@ -1287,7 +1361,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
     }, async ({ workspaceId, name, action, arguments: capabilityArguments, file }, extra) => {
         const workspace = workspaces.getWorkspace(workspaceId);
         let changedPaths = [];
-        return runToolWithHooks(hooks, {
+        return runActivityToolWithHooks(activityLifecycle, hooks, workspace, extra._meta, { workspaceId, name, action, arguments: capabilityArguments, file }, {
             signal: extra.signal,
             tool: toolNames.capability,
             invocation: workspaceHookInvocation(workspace),
@@ -1510,7 +1584,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         annotations: { readOnlyHint: true },
     }, async ({ workspaceId, ...input }, extra) => {
         const workspace = workspaces.getWorkspace(workspaceId);
-        return runToolWithHooks(hooks, {
+        return runActivityToolWithHooks(activityLifecycle, hooks, workspace, extra._meta, { workspaceId, ...input }, {
             signal: extra.signal,
             tool: toolNames.read,
             invocation: workspaceHookInvocation(workspace),
@@ -1597,7 +1671,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             annotations: WRITE_TOOL_ANNOTATIONS,
         }, async ({ workspaceId, ...input }, extra) => {
             const workspace = workspaces.getWorkspace(workspaceId);
-            return runToolWithHooks(hooks, {
+            return runActivityToolWithHooks(activityLifecycle, hooks, workspace, extra._meta, { workspaceId, ...input }, {
                 signal: extra.signal,
                 tool: toolNames.write,
                 invocation: workspaceHookInvocation(workspace),
@@ -1681,7 +1755,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             annotations: EDIT_TOOL_ANNOTATIONS,
         }, async ({ workspaceId, ...input }, extra) => {
             const workspace = workspaces.getWorkspace(workspaceId);
-            return runToolWithHooks(hooks, {
+            return runActivityToolWithHooks(activityLifecycle, hooks, workspace, extra._meta, { workspaceId, ...input }, {
                 signal: extra.signal,
                 tool: toolNames.edit,
                 invocation: workspaceHookInvocation(workspace),
@@ -1758,7 +1832,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         annotations: EDIT_TOOL_ANNOTATIONS,
     }, async ({ workspaceId, path, newPath }, extra) => {
         const workspace = workspaces.getWorkspace(workspaceId);
-        return runToolWithHooks(hooks, {
+        return runActivityToolWithHooks(activityLifecycle, hooks, workspace, extra._meta, { workspaceId, path, newPath }, {
             signal: extra.signal,
             tool: toolNames.rename,
             invocation: workspaceHookInvocation(workspace),
@@ -1831,7 +1905,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         annotations: EDIT_TOOL_ANNOTATIONS,
     }, async ({ workspaceId, path, recursive }, extra) => {
         const workspace = workspaces.getWorkspace(workspaceId);
-        return runToolWithHooks(hooks, {
+        return runActivityToolWithHooks(activityLifecycle, hooks, workspace, extra._meta, { workspaceId, path, recursive }, {
             signal: extra.signal,
             tool: toolNames.delete,
             invocation: workspaceHookInvocation(workspace),
@@ -1912,7 +1986,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             annotations: EDIT_TOOL_ANNOTATIONS,
         }, async ({ workspaceId, patch }, extra) => {
             const workspace = workspaces.getWorkspace(workspaceId);
-            return runToolWithHooks(hooks, {
+            return runActivityToolWithHooks(activityLifecycle, hooks, workspace, extra._meta, { workspaceId, patch }, {
                 signal: extra.signal,
                 tool: "apply_patch",
                 invocation: workspaceHookInvocation(workspace),
@@ -2048,69 +2122,82 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     throw new Error("bash action=run does not accept processId, input, or interrupt.");
                 }
                 let undeliveredProcessId;
-                try {
-                    const result = await runToolWithHooks(hooks, {
-                        signal: extra.signal,
-                        tool: toolNames.shell,
-                        invocation: workspaceHookInvocation(workspace),
-                        payload: {
-                            action,
-                            command,
-                            workingDirectory: workingDirectory ?? ".",
-                        },
-                        isFailure: toolResultIsError,
-                        operation: async () => {
-                            const startedAt = performance.now();
-                            const cwd = workspaces.resolveWorkingDirectory(workspace, workingDirectory);
-                            await assertWorkspaceInstructionsLoadedBeforeSideEffect(workspaces, workspace, [cwd]);
-                            const snapshot = await processSessions.start({
-                                workspaceId,
-                                command,
-                                cwd,
-                                workspaceRoot: workspace.root,
-                                tty,
-                                columns,
-                                rows,
-                                yieldTimeMs,
-                                timeoutMs,
-                                maxOutputTokens,
-                                signal: extra.signal,
-                            });
-                            undeliveredProcessId = snapshot.running ? snapshot.processId : undefined;
-                            logToolCall(config, {
-                                tool: toolNames.shell,
-                                ...workspaceLogContext(workspace, extra.sessionId),
-                                workingDirectory: workingDirectory ?? ".",
-                                command,
-                                commandLength: command.length,
-                                exitCode: snapshot.exitCode,
-                                running: snapshot.running,
-                                processId: snapshot.processId,
-                                success: snapshot.running || (snapshot.exitCode === 0 && !snapshot.signal),
-                                durationMs: Math.round(performance.now() - startedAt),
-                            });
-                            const response = processToolResponse(toolNames.shell, workspaceId, snapshot, {
+                return runActivityTool(activityLifecycle, workspace, extra._meta, toolNames.shell, {
+                    workspaceId,
+                    action,
+                    command,
+                    tty,
+                    columns,
+                    rows,
+                    workingDirectory,
+                    yieldTimeMs,
+                    timeoutMs,
+                    maxOutputTokens,
+                }, async () => {
+                    try {
+                        const result = await runToolWithHooks(hooks, {
+                            signal: extra.signal,
+                            tool: toolNames.shell,
+                            invocation: workspaceHookInvocation(workspace),
+                            payload: {
                                 action,
                                 command,
                                 workingDirectory: workingDirectory ?? ".",
-                                running: snapshot.running,
-                                exitCode: snapshot.exitCode,
-                                wallTimeMs: snapshot.wallTimeMs,
-                            });
-                            return !snapshot.running && (snapshot.signal || snapshot.exitCode !== 0)
-                                ? { ...response, isError: true }
-                                : response;
-                        },
-                    });
-                    extra.signal.throwIfAborted();
-                    return result;
-                }
-                catch (error) {
-                    if (undeliveredProcessId !== undefined) {
-                        processSessions.discardUndelivered(workspaceId, undeliveredProcessId);
+                            },
+                            isFailure: toolResultIsError,
+                            operation: async () => {
+                                const startedAt = performance.now();
+                                const cwd = workspaces.resolveWorkingDirectory(workspace, workingDirectory);
+                                await assertWorkspaceInstructionsLoadedBeforeSideEffect(workspaces, workspace, [cwd]);
+                                const snapshot = await processSessions.start({
+                                    workspaceId,
+                                    command,
+                                    cwd,
+                                    workspaceRoot: workspace.root,
+                                    tty,
+                                    columns,
+                                    rows,
+                                    yieldTimeMs,
+                                    timeoutMs,
+                                    maxOutputTokens,
+                                    signal: extra.signal,
+                                });
+                                undeliveredProcessId = snapshot.running ? snapshot.processId : undefined;
+                                logToolCall(config, {
+                                    tool: toolNames.shell,
+                                    ...workspaceLogContext(workspace, extra.sessionId),
+                                    workingDirectory: workingDirectory ?? ".",
+                                    command,
+                                    commandLength: command.length,
+                                    exitCode: snapshot.exitCode,
+                                    running: snapshot.running,
+                                    processId: snapshot.processId,
+                                    success: snapshot.running || (snapshot.exitCode === 0 && !snapshot.signal),
+                                    durationMs: Math.round(performance.now() - startedAt),
+                                });
+                                const response = processToolResponse(toolNames.shell, workspaceId, snapshot, {
+                                    action,
+                                    command,
+                                    workingDirectory: workingDirectory ?? ".",
+                                    running: snapshot.running,
+                                    exitCode: snapshot.exitCode,
+                                    wallTimeMs: snapshot.wallTimeMs,
+                                });
+                                return !snapshot.running && (snapshot.signal || snapshot.exitCode !== 0)
+                                    ? { ...response, isError: true }
+                                    : response;
+                            },
+                        });
+                        extra.signal.throwIfAborted();
+                        return result;
                     }
-                    throw error;
-                }
+                    catch (error) {
+                        if (undeliveredProcessId !== undefined) {
+                            processSessions.discardUndelivered(workspaceId, undeliveredProcessId);
+                        }
+                        throw error;
+                    }
+                }, processActivityOutcome);
             }
             if (command !== undefined || workingDirectory !== undefined || tty !== undefined || timeoutMs !== undefined) {
                 throw new Error("bash action=process does not accept command, workingDirectory, tty, or timeoutMs.");
@@ -2167,7 +2254,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             });
         });
     }
-    registerProcessTools(server, config, workspaces, processSessions, hooks);
+    registerProcessTools(server, config, workspaces, processSessions, hooks, activityLifecycle);
     return server;
 }
 export function createServer(config = loadConfig(), options = {}) {
@@ -2193,6 +2280,8 @@ export function createServer(config = loadConfig(), options = {}) {
     });
     const workspaceStore = createWorkspaceStore(config.stateDir);
     const workspaces = new WorkspaceRegistry(config, workspaceStore);
+    const activityAuditStore = new ActivityAuditStore(config.stateDir);
+    const activityLifecycle = new ActivityLifecycle(activityAuditStore);
     const reviewCheckpoints = createReviewCheckpointManager();
     const processSessions = new ProcessManager();
     const codeIntelligence = new CodeIntelligenceManager(config);
@@ -2379,7 +2468,7 @@ export function createServer(config = loadConfig(), options = {}) {
                         });
                     }
                 };
-                const server = createMcpServer(config, workspaces, reviewCheckpoints, processSessions, localAgentProviders, incomingArtifactAdapters, codeIntelligence);
+                const server = createMcpServer(config, workspaces, reviewCheckpoints, processSessions, localAgentProviders, incomingArtifactAdapters, codeIntelligence, activityLifecycle);
                 await server.connect(transport);
             }
             else {
@@ -2411,6 +2500,7 @@ export function createServer(config = loadConfig(), options = {}) {
                 processSessions.shutdown();
                 await codeIntelligence.shutdown();
                 oauthProvider.close();
+                activityAuditStore.close();
                 workspaceStore.close?.();
             })();
             return closePromise;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akira-tl/forgerelay",
-  "version": "0.4.7",
+  "version": "0.5.1",
   "description": "Local development control plane for MCP coding agents.",
   "type": "module",
   "homepage": "https://github.com/Akira-TL/forgerelay#readme",
@@ -44,7 +44,7 @@
     "release:parity": "node scripts/release-parity.mjs",
     "postinstall": "node scripts/fix-node-pty-permissions.mjs",
     "start": "node dist/cli.js serve",
-    "test": "node --test scripts/release-proof.test.mjs && tsx src/config.test.ts && tsx src/lsp/language-server-config.test.ts && tsx src/lsp/normalization/hover.test.ts && tsx src/lsp/references.server.test.ts && tsx src/lsp/operations/document-symbols.server.test.ts && tsx src/lsp/operations/workspace-symbols.server.test.ts && tsx src/lsp/operations/diagnostics-push.server.test.ts && tsx src/lsp/operations/diagnostics-pull.server.test.ts && tsx src/lsp/operations/request-hardening.server.test.ts && tsx src/lsp/operations/recovery.server.test.ts && tsx src/lsp/operations/lifecycle.server.test.ts && tsx src/lsp/runtime/semantic-requests.test.ts && tsx src/logger.test.ts && tsx src/proxy-trust.test.ts && tsx src/mcp-app-template.test.ts && tsx src/hooks.test.ts && tsx src/capability-registry.test.ts && tsx src/mcp/server-instructions.test.ts && tsx src/request-meta.test.ts && tsx src/incoming-artifacts.test.ts && tsx src/artifact-download.test.ts && tsx src/ui/card-types.test.ts && tsx src/ui/patch-display.test.ts && tsx src/ui/tool-display.test.ts && tsx src/apply-patch.test.ts && tsx src/process-platform.test.ts && tsx src/process-sessions.test.ts && tsx src/mcp-sessions.test.ts && tsx src/server-shutdown.test.ts && tsx src/local-agent-runtime.test.ts && tsx src/local-agent-adapters.test.ts && tsx src/local-agent-availability.test.ts && tsx src/local-agent-profiles.test.ts && tsx src/local-agent-targets.test.ts && tsx src/local-agent-store.test.ts && tsx src/roots.test.ts && tsx src/file-mutations.test.ts && tsx src/skills.test.ts && tsx src/workspace-store.test.ts && tsx src/workspaces.test.ts && tsx src/workspace-conversation.test.ts && tsx src/review-checkpoints.test.ts && tsx src/lsp/code-intelligence.server.test.ts && tsx src/server.test.ts && tsx src/oauth-store.test.ts && tsx src/cli.test.ts",
+    "test": "node --test scripts/release-proof.test.mjs && tsx src/config.test.ts && tsx src/lsp/language-server-config.test.ts && tsx src/lsp/normalization/hover.test.ts && tsx src/lsp/references.server.test.ts && tsx src/lsp/operations/document-symbols.server.test.ts && tsx src/lsp/operations/workspace-symbols.server.test.ts && tsx src/lsp/operations/diagnostics-push.server.test.ts && tsx src/lsp/operations/diagnostics-pull.server.test.ts && tsx src/lsp/operations/request-hardening.server.test.ts && tsx src/lsp/operations/recovery.server.test.ts && tsx src/lsp/operations/lifecycle.server.test.ts && tsx src/lsp/runtime/semantic-requests.test.ts && tsx src/logger.test.ts && tsx src/proxy-trust.test.ts && tsx src/mcp-app-template.test.ts && tsx src/hooks.test.ts && tsx src/capability-registry.test.ts && tsx src/mcp/server-instructions.test.ts && tsx src/request-meta.test.ts && tsx src/incoming-artifacts.test.ts && tsx src/artifact-download.test.ts && tsx src/ui/card-types.test.ts && tsx src/ui/patch-display.test.ts && tsx src/ui/tool-display.test.ts && tsx src/apply-patch.test.ts && tsx src/process-platform.test.ts && tsx src/process-sessions.test.ts && tsx src/mcp-sessions.test.ts && tsx src/server-shutdown.test.ts && tsx src/local-agent-runtime.test.ts && tsx src/local-agent-adapters.test.ts && tsx src/local-agent-availability.test.ts && tsx src/local-agent-profiles.test.ts && tsx src/local-agent-targets.test.ts && tsx src/local-agent-store.test.ts && tsx src/roots.test.ts && tsx src/file-mutations.test.ts && tsx src/skills.test.ts && tsx src/workspace-store.test.ts && tsx src/activity/audit-store.test.ts && tsx src/activity/lifecycle.test.ts && tsx src/workspaces.test.ts && tsx src/workspace-conversation.test.ts && tsx src/review-checkpoints.test.ts && tsx src/lsp/code-intelligence.server.test.ts && tsx src/server.test.ts && tsx src/oauth-store.test.ts && tsx src/cli.test.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "release:check": "node scripts/release-version.mjs check",
     "release:tag-check": "node scripts/release-version.mjs tag",