forge-openclaw-plugin 0.2.48 → 0.2.50

package/dist/server/server/src/app.js

@@ -2643,7 +2643,7 @@ const AGENT_ONBOARDING_ENTITY_CATALOG = [
     }),
     enrichOnboardingEntityGuide({
         entityType: "wiki_page",
-        purpose: "A file-backed Forge wiki page or evidence page.",
+        purpose: "A SQLite-backed Forge wiki page or evidence page.",
         minimumCreateFields: ["title", "contentMarkdown"],
         relationshipRules: [
             "Wiki pages live on the wiki surface and use specialized page upsert routes rather than batch CRUD.",
@@ -2772,6 +2772,12 @@ const AGENT_ONBOARDING_CONVERSATION_RULES = [
     "When useful, help the user name, define, and connect the record in that order: offer a working label, clarify what belongs inside it, then ask about links only after the record itself feels steady.",
     "When the meaning is clearer than the wording, offer a tentative title or formulation yourself and invite correction instead of forcing the user to wordsmith alone.",
     "For direct update or review requests, the next question should usually narrow the saved object, timeframe, or route family instead of reopening the whole meaning-making arc.",
+    "For updates, start with the smallest thing that now feels wrong, newly true, or newly visible rather than restarting the whole story.",
+    "For review requests, ask what practical question the user wants the read to answer before you ask for more scope.",
+    "The opening question should help the user understand what they are actually trying to save, decide, review, or change, not make them perform the schema out loud.",
+    "If the user already named the exact correction in usable language, confirm only the missing scope, timing, or route-selecting detail that still matters, then act.",
+    "Once a specialized-surface lane is clear, speak in route-relevant nouns such as timeline, overlay, weekday template, published output, run detail, or node result instead of generic record language.",
+    "If the next answer would not change the route, wording, timing, or write payload in a meaningful way, stop asking and act.",
     "Before saving, briefly summarize the working formulation in the user's own language when that would reduce ambiguity.",
     "Once the record is clear enough to name, stop exploring broadly and ask only for the last structural detail that still matters.",
     "If the record is already clear enough to save, save it instead of performing a ceremonial extra question.",
@@ -3546,7 +3552,7 @@ const AGENT_ONBOARDING_TOOL_INPUT_CATALOG = [
         requiredFields: [],
         notes: [
             "Semantic search is optional and profile-driven.",
-            "The wiki is file-first, so spaces map to local vault directories."
+            "The wiki is SQLite-backed, so pages and evidence live in Forge's database."
         ],
         example: "{}"
     },
@@ -3588,13 +3594,13 @@ const AGENT_ONBOARDING_TOOL_INPUT_CATALOG = [
     },
     {
         toolName: "forge_upsert_wiki_page",
-        summary: "Create a new wiki page or update an existing one through the file-backed wiki surface.",
+        summary: "Create a new wiki page or update an existing one through the SQLite-backed wiki surface.",
         whenToUse: "Use when the user explicitly wants wiki memory persisted or reorganized.",
         inputShape: '{ pageId?: string, kind?: "wiki"|"evidence", title: string, slug?: string, summary?: string, aliases?: string[], contentMarkdown: string, author?: string|null, tags?: string[], spaceId?: string, frontmatter?: object, links?: Array<{ entityType, entityId, anchorKey? }> }',
         requiredFields: ["title", "contentMarkdown"],
         notes: [
             "When pageId is omitted, Forge creates a new page.",
-            "When pageId is present, Forge patches the existing page and rewrites the canonical file."
+            "When pageId is present, Forge patches the existing SQLite note record."
         ],
         example: '{"title":"Taste map","contentMarkdown":"# Taste map\\n\\n[[forge:goal:goal_123|Core goal]] influences this page.","spaceId":"wiki_space_shared"}'
     },
@@ -3605,19 +3611,19 @@ const AGENT_ONBOARDING_TOOL_INPUT_CATALOG = [
         inputShape: "{ spaceId?: string }",
         requiredFields: [],
         notes: [
-            "This is the explicit health surface for the file-first wiki vault.",
+            "This is the explicit health surface for the SQLite-backed wiki memory layer.",
             "Use it before proposing cleanup work or auto-maintenance."
         ],
         example: '{"spaceId":"wiki_space_shared"}'
     },
     {
         toolName: "forge_sync_wiki_vault",
-        summary: "Resync Markdown files from the local wiki vault into Forge metadata.",
-        whenToUse: "Use after out-of-band file edits or imported file changes that should be reflected back in Forge.",
+        summary: "Rebuild SQLite wiki search, link, and metadata indexes.",
+        whenToUse: "Use after large SQLite wiki changes or maintenance work that should refresh derived metadata.",
         inputShape: "{ spaceId?: string }",
         requiredFields: [],
         notes: [
-            "Forge treats the vault as a first-class local artifact, so this route is the bridge back into app metadata."
+            "Forge treats SQLite as the canonical wiki store; this route refreshes derived indexes."
         ],
         example: '{"spaceId":"wiki_space_shared"}'
     },
@@ -3636,11 +3642,11 @@ const AGENT_ONBOARDING_TOOL_INPUT_CATALOG = [
     {
         toolName: "forge_ingest_wiki_source",
         summary: "Ingest raw text, local files, or URLs into the wiki, preserving a raw source artifact and returning page plus proposal outputs.",
-        whenToUse: "Use when the operator wants source material compiled into file-first wiki memory and optional Forge-entity proposals.",
+        whenToUse: "Use when the operator wants source material compiled into SQLite-backed wiki memory and optional Forge-entity proposals.",
         inputShape: '{ spaceId?: string, titleHint?: string, sourceKind: "raw_text"|"local_path"|"url", sourceText?: string, sourcePath?: string, sourceUrl?: string, mimeType?: string, llmProfileId?: string, parseStrategy?: "auto"|"text_only"|"multimodal", entityProposalMode?: "none"|"suggest", createAsKind?: "wiki"|"evidence", linkedEntityHints?: Array<{ entityType, entityId, anchorKey? }> }',
         requiredFields: ["sourceKind", "sourceText/sourcePath/sourceUrl"],
         notes: [
-            "Forge preserves a raw artifact under the wiki space's raw directory.",
+            "Forge preserves a raw ingest artifact separately from SQLite page content.",
             "Entity proposals are suggestions only; they are not auto-applied."
         ],
         example: '{"sourceKind":"url","sourceUrl":"https://example.com/article","titleHint":"Research import","parseStrategy":"auto","entityProposalMode":"suggest"}'
@@ -4013,7 +4019,7 @@ function buildAgentOnboardingPayload(request) {
             task: "A concrete actionable work item. Task status is board state, not proof of live work.",
             taskRun: "A live work session attached to a task. Start, heartbeat, focus, complete, and release runs instead of faking work with status alone.",
             note: "A Markdown work note that can link to one or many entities. Use notes for progress evidence, context, and close-out summaries.",
-            wiki: "Forge Wiki is the file-first memory layer: local Markdown pages plus media, backlinks, optional embeddings, explicit spaces, and structured links back to Forge entities.",
+            wiki: "Forge Wiki is the SQLite-backed memory layer: Markdown content in notes rows plus media, backlinks, optional embeddings, explicit spaces, and structured links back to Forge entities.",
             sleepSession: "A sleep session is a first-class health record with timing, sleep and bed duration, stage breakdown, recovery metrics, annotations, and Forge links back to planning or Psyche context.",
             workoutSession: "A workout session is a first-class sports record imported from HealthKit or generated from a habit. It holds workout type, timing, energy or distance when available, subjective effort, narrative context, and Forge links.",
             preferences: "Forge Preferences is the explicit taste-modeling domain. It has workspaces, contexts, concept libraries, direct items, pairwise judgments, direct signals, and inferred scores.",
@@ -4157,6 +4163,11 @@ function buildAgentOnboardingPayload(request) {
             specializedDomainSurfaces: {
                 movement: {
                     summary: "Dedicated movement workspace API. Use these routes for stays, trips, time-in-place questions, visited places, trip detail, selection aggregates, user-defined overlays, and repair actions on already-recorded movement data.",
+                    routeSelectionQuestions: [
+                        "Is the user asking for a day, month, all-time, timeline, place, trip detail, or selected-span answer?",
+                        "Is this a missing-gap overlay, a saved-overlay repair, or an edit to one already-recorded stay, trip, or trip point?",
+                        "If the target is already known, what one time, place, or saved-object detail is still missing before acting?"
+                    ],
                     readRoutes: {
                         day: "/api/v1/movement/day",
                         month: "/api/v1/movement/month",
@@ -4194,6 +4205,11 @@ function buildAgentOnboardingPayload(request) {
                 },
                 lifeForce: {
                     summary: "Dedicated life-force API. Use it to read the current energy budget, drains, recommendations, and warnings, then patch only the parts that are meant to be user-controlled.",
+                    routeSelectionQuestions: [
+                        "Is the user trying to understand the overview, change durable profile assumptions, change a weekday curve, or log a right-now fatigue signal?",
+                        "Are they describing a repeatable weekly shape or a one-off current state?",
+                        "If the lane is already clear, what one weekday, profile field, or signal detail is still missing?"
+                    ],
                     readRoutes: {
                         overview: "/api/v1/life-force"
                     },
@@ -4206,12 +4222,18 @@ function buildAgentOnboardingPayload(request) {
                         "Life Force is a focused domain surface, not a batch CRUD entity type.",
                         "Use GET /api/v1/life-force for the current overview payload with stats, drains, recommendations, and current-curve state.",
                         "Patch the profile only for durable personal settings, update weekday templates only for the curve itself, and post fatigue signals for real-time tired or recovered observations.",
+                        "If the user says something like 'I always dip on Tuesdays after lunch', treat that as a weekday-template change rather than a one-off fatigue signal.",
                         "If the user is asking what changed after a profile, template, or fatigue write, read the overview back so the effect stays visible.",
                         "If the user already knows they want a profile change, weekday-template edit, or right-now fatigue signal, skip the broad lane question and ask only for the missing weekday, profile field, or signal detail."
                     ]
                 },
                 workbench: {
                     summary: "Dedicated graph-flow API. Use it for flow catalog reads, flow CRUD, execution, run history, published outputs, node results, and latest successful node outputs.",
+                    routeSelectionQuestions: [
+                        "Is the job flow discovery, flow editing, execution, published output, run detail, node result, latest node output, or flow chat follow-up?",
+                        "Does the user need a stable public contract or one execution artifact?",
+                        "If the flow is already known, what one run, node, or output scope detail is still missing before acting?"
+                    ],
                     readRoutes: {
                         listFlows: "/api/v1/workbench/flows",
                         flowById: "/api/v1/workbench/flows/:id",
@@ -4237,6 +4259,7 @@ function buildAgentOnboardingPayload(request) {
                         "Use the flow routes when the agent needs stable public input contracts, published outputs, node-level results, or reusable execution history.",
                         "If the user is still figuring out inputs or editable structure, read flow detail or box catalog before asking them to author a payload from memory.",
                         "Prefer the dedicated output and node-result routes over reverse-engineering raw traces.",
+                        "If the user only wants a published output, latest node output, or run detail, do not reopen a flow-edit intake before reading that artifact.",
                         "If the user already named the flow and wants one output or one run, skip the broad lane question and ask only for the missing run, node, or output scope."
                     ]
                 }
@@ -4358,17 +4381,26 @@ function buildAgentOnboardingPayload(request) {
             movementTimeline: "/api/v1/movement/timeline",
             movementAllTime: "/api/v1/movement/all-time",
             movementPlaces: "/api/v1/movement/places",
+            movementBoxDetail: "/api/v1/movement/boxes/:id",
+            movementSettings: "/api/v1/movement/settings",
+            movementSettingsUpdate: "/api/v1/movement/settings",
             movementTripDetail: "/api/v1/movement/trips/:id",
             movementSelection: "/api/v1/movement/selection",
             movementUserBoxPreflight: "/api/v1/movement/user-boxes/preflight",
             movementUserBoxUpdate: "/api/v1/movement/user-boxes/:id",
+            movementUserBoxDelete: "/api/v1/movement/user-boxes/:id",
             movementAutomaticBoxInvalidate: "/api/v1/movement/automatic-boxes/:id/invalidate",
             movementStayUpdate: "/api/v1/movement/stays/:id",
+            movementStayDelete: "/api/v1/movement/stays/:id",
             movementTripUpdate: "/api/v1/movement/trips/:id",
+            movementTripDelete: "/api/v1/movement/trips/:id",
             movementTripPointUpdate: "/api/v1/movement/trips/:id/points/:pointId",
+            movementTripPointDelete: "/api/v1/movement/trips/:id/points/:pointId",
+            workbenchBoxCatalog: "/api/v1/workbench/catalog/boxes",
             workbenchFlows: "/api/v1/workbench/flows",
             workbenchFlowBySlug: "/api/v1/workbench/flows/by-slug/:slug",
             workbenchPublishedOutput: "/api/v1/workbench/flows/:id/output",
+            workbenchRuns: "/api/v1/workbench/flows/:id/runs",
             workbenchRunDetail: "/api/v1/workbench/flows/:id/runs/:runId",
             workbenchNodeResult: "/api/v1/workbench/flows/:id/runs/:runId/nodes/:nodeId",
             workbenchLatestNodeOutput: "/api/v1/workbench/flows/:id/nodes/:nodeId/output",
@@ -4444,9 +4476,9 @@ function buildAgentOnboardingPayload(request) {
             saveSuggestionPlacement: "end_of_message",
             saveSuggestionTone: "gentle_optional",
             maxQuestionsPerTurn: 1,
-            psycheExplorationRule: "When a Psyche entity needs understanding first, begin with one exploratory question before any working formulation, replacement belief, suggested title, or save pitch. Keep the opening reflection to one or two short sentences, stay in plain prose instead of bullets or numbered lists, keep that first reply short, do not mention Forge search or save structure yet, avoid colons or list-shaped phrasing, prefer what/when/how over why until the experience is grounded, wait for the user's answer before offering a fuller formulation, ask permission before moving from charged exploration into naming or challenge when needed, do not widen into adjacent entities until the current one has a working sentence the user recognizes, and once the lived experience is coherent stop deepening and help the user name it cleanly. When the user is updating a Psyche record because of one fresh episode, anchor in that episode before renaming the durable formulation. If the user accepts the wording, move toward the save instead of reopening deeper exploration.",
-            specializedSurfaceRule: "For Movement, Life Force, and Workbench, clarify the lane first, then name the dedicated route family in plain language and do not guess at a generic CRUD path. If the truth of the current state is still uncertain, read the relevant specialized view before you mutate it. When the user already named a precise correction or review target, confirm only the route-selecting detail that is still missing. After a concrete specialized-surface correction, read the relevant specialized view back when the user is trying to understand the result rather than just store it. The canonical runtime routes stay under /api/v1/*, and the OpenClaw HTTP mirror exposes the same families under /forge/v1/movement, /forge/v1/life-force, and /forge/v1/workbench.",
-            reviewShortcutRule: "When the user is reviewing or correcting an existing record, narrow the saved object, timeframe, or route family first. Do not reopen the whole intake unless the user is actually redefining the record.",
+            psycheExplorationRule: "When a Psyche entity needs understanding first, begin with one exploratory question before any working formulation, replacement belief, suggested title, or save pitch. Keep the opening reflection to one or two short sentences, stay in plain prose instead of bullets or numbered lists, keep that first reply short, do not mention Forge search or save structure yet, avoid colons or list-shaped phrasing, prefer what/when/how over why until the experience is grounded, wait for the user's answer before offering a fuller formulation, ask permission before moving from charged exploration into naming or challenge when needed, make the next question help the user feel more able to name the experience rather than more examined, do not widen into adjacent entities until the current one has a working sentence the user recognizes, and once the lived experience is coherent stop deepening and help the user name it cleanly. When the user is updating a Psyche record because of one fresh episode, anchor in that episode before renaming the durable formulation, begin with the smallest part of the old wording that no longer fits, and do not reopen the full origin story unless the new understanding is truly structural. If the user accepts the wording, move toward the save instead of reopening deeper exploration.",
+            specializedSurfaceRule: "For Movement, Life Force, and Workbench, clarify the lane first, then name the dedicated route family in plain language and do not guess at a generic CRUD path. Use specializedDomainSurfaces.routeSelectionQuestions when they are present so the next follow-up stays route-selective instead of generic. Once the lane is clear, talk in route-relevant nouns such as timeline, overlay, weekday template, published output, run detail, or node result rather than generic record language. If the truth of the current state is still uncertain, read the relevant specialized view before you mutate it. When the user already named a precise correction or review target, confirm only the route-selecting detail that is still missing. After a concrete specialized-surface correction, read the relevant specialized view back when the user is trying to understand the result rather than just store it. The canonical runtime routes stay under /api/v1/*, and the OpenClaw HTTP mirror exposes the same families under /forge/v1/movement, /forge/v1/life-force, and /forge/v1/workbench.",
+            reviewShortcutRule: "When the user is reviewing or correcting an existing record, ask what practical question they want the read or correction to answer, then narrow the saved object, timeframe, or route family first. Do not reopen the whole intake unless the user is actually redefining the record.",
             readModelWriteRule: "Self-observation is note-backed and should be written through observed notes with frontmatter.observedAt. Sleep and workout sessions stay on batch CRUD by default; use the reflective review helpers only when enriching one already-known record after review.",
             psycheOpeningQuestionRule: "Prefer a concrete opening question tied to the entity: ask when the value mattered, what happened the last time the pattern appeared, what cue or body signal came first before the behavior, what the belief starts saying about self or outcome, what feels most at risk inside the mode, what the part is trying to get the user to do or stop doing, or where the shift began in the incident. Reflect briefly before the question, choose one follow-up lane at a time, say what is becoming clearer before the next deeper question, and if several Psyche entities are visible hold the adjacent ones lightly until the main container is clear.",
             duplicateCheckRoute: "/api/v1/entities/search",

package/dist/server/server/src/db.js

@@ -34,14 +34,12 @@ function resolveLegacyDatabasePath(root = dataRoot) {
 function hasCanonicalRuntimeLayout(root = dataRoot) {
     const canonicalRoot = resolveCanonicalDataDir(root);
     return (existsSync(resolveCanonicalDatabasePath(root)) ||
-        existsSync(path.join(canonicalRoot, "wiki")) ||
         existsSync(path.join(canonicalRoot, "wiki-ingest")) ||
         existsSync(path.join(canonicalRoot, ".forge-secrets.key")));
 }
 function hasLegacyRuntimeLayout(root = dataRoot) {
     const legacyRoot = resolveLegacyDataDir(root);
     return (existsSync(resolveLegacyDatabasePath(root)) ||
-        existsSync(path.join(legacyRoot, "wiki")) ||
         existsSync(path.join(legacyRoot, "wiki-ingest")) ||
         existsSync(path.join(legacyRoot, ".forge-secrets.key")));
 }

package/dist/server/server/src/openapi.js

@@ -2137,6 +2137,11 @@ export function buildOpenApiDocument() {
             "id",
             "label",
             "agentType",
+            "identityKey",
+            "provider",
+            "machineKey",
+            "personaKey",
+            "linkedUsers",
             "trustLevel",
             "autonomyMode",
             "approvalMode",
@@ -2150,6 +2155,20 @@ export function buildOpenApiDocument() {
             id: { type: "string" },
             label: { type: "string" },
             agentType: { type: "string" },
+            identityKey: nullable({ type: "string" }),
+            provider: nullable({ type: "string", enum: ["openclaw", "hermes", "codex"] }),
+            machineKey: nullable({ type: "string" }),
+            personaKey: nullable({ type: "string" }),
+            linkedUsers: arrayOf({
+                type: "object",
+                additionalProperties: false,
+                required: ["userId", "role", "user"],
+                properties: {
+                    userId: { type: "string" },
+                    role: { type: "string" },
+                    user: nullable({ $ref: "#/components/schemas/UserSummary" })
+                }
+            }),
             trustLevel: {
                 type: "string",
                 enum: ["standard", "trusted", "autonomous"]
@@ -3234,17 +3253,26 @@ export function buildOpenApiDocument() {
                     "movementTimeline",
                     "movementAllTime",
                     "movementPlaces",
+                    "movementBoxDetail",
+                    "movementSettings",
+                    "movementSettingsUpdate",
                     "movementTripDetail",
                     "movementSelection",
                     "movementUserBoxPreflight",
                     "movementUserBoxUpdate",
+                    "movementUserBoxDelete",
                     "movementAutomaticBoxInvalidate",
                     "movementStayUpdate",
+                    "movementStayDelete",
                     "movementTripUpdate",
+                    "movementTripDelete",
                     "movementTripPointUpdate",
+                    "movementTripPointDelete",
+                    "workbenchBoxCatalog",
                     "workbenchFlows",
                     "workbenchFlowBySlug",
                     "workbenchPublishedOutput",
+                    "workbenchRuns",
                     "workbenchRunDetail",
                     "workbenchNodeResult",
                     "workbenchLatestNodeOutput",
@@ -3273,17 +3301,26 @@ export function buildOpenApiDocument() {
                     movementTimeline: { type: "string" },
                     movementAllTime: { type: "string" },
                     movementPlaces: { type: "string" },
+                    movementBoxDetail: { type: "string" },
+                    movementSettings: { type: "string" },
+                    movementSettingsUpdate: { type: "string" },
                     movementTripDetail: { type: "string" },
                     movementSelection: { type: "string" },
                     movementUserBoxPreflight: { type: "string" },
                     movementUserBoxUpdate: { type: "string" },
+                    movementUserBoxDelete: { type: "string" },
                     movementAutomaticBoxInvalidate: { type: "string" },
                     movementStayUpdate: { type: "string" },
+                    movementStayDelete: { type: "string" },
                     movementTripUpdate: { type: "string" },
+                    movementTripDelete: { type: "string" },
                     movementTripPointUpdate: { type: "string" },
+                    movementTripPointDelete: { type: "string" },
+                    workbenchBoxCatalog: { type: "string" },
                     workbenchFlows: { type: "string" },
                     workbenchFlowBySlug: { type: "string" },
                     workbenchPublishedOutput: { type: "string" },
+                    workbenchRuns: { type: "string" },
                     workbenchRunDetail: { type: "string" },
                     workbenchNodeResult: { type: "string" },
                     workbenchLatestNodeOutput: { type: "string" },
@@ -4811,6 +4848,24 @@ export function buildOpenApiDocument() {
                     }
                 }
             },
+            "/api/v1/movement/boxes/{id}": {
+                get: {
+                    summary: "Read one movement box with projected detail, provenance, and raw linked evidence",
+                    responses: {
+                        "200": jsonResponse({
+                            type: "object",
+                            required: ["movement"],
+                            properties: {
+                                movement: {
+                                    type: "object",
+                                    additionalProperties: true
+                                }
+                            }
+                        }, "Movement box detail"),
+                        "404": { $ref: "#/components/responses/Error" }
+                    }
+                }
+            },
             "/api/v1/movement/trips/{id}": {
                 get: {
                     summary: "Read one movement trip with its full detail",
@@ -5241,7 +5296,7 @@ export function buildOpenApiDocument() {
                     }
                 },
                 post: {
-                    summary: "Create a wiki page through the file-backed wiki surface",
+                    summary: "Create a wiki page through the SQLite-backed wiki surface",
                     responses: {
                         "200": jsonResponse({
                             type: "object",
@@ -5269,7 +5324,7 @@ export function buildOpenApiDocument() {
                     }
                 },
                 patch: {
-                    summary: "Update an existing wiki page through the file-backed surface",
+                    summary: "Update an existing wiki page through the SQLite-backed surface",
                     responses: {
                         "200": jsonResponse({
                             type: "object",
@@ -5315,7 +5370,7 @@ export function buildOpenApiDocument() {
             },
             "/api/v1/wiki/sync": {
                 post: {
-                    summary: "Resync markdown files from the local wiki vault into Forge metadata",
+                    summary: "Rebuild SQLite wiki search, link, and metadata indexes",
                     responses: {
                         "200": jsonResponse({
                             type: "object",

package/dist/server/server/src/repositories/agent-runtime-sessions.js

@@ -1,7 +1,8 @@
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { getDatabase, runInTransaction } from "../db.js";
 import { recordActivityEvent } from "./activity-events.js";
 import { listAgentActions } from "./collaboration.js";
+import { ensureBotUser, getUserById } from "./users.js";
 import { agentActionSchema, agentRuntimeEventLevelSchema, agentRuntimeReconnectPlanSchema, agentRuntimeSessionEventSchema, agentRuntimeSessionSchema, createAgentRuntimeSessionEventSchema, createAgentRuntimeSessionSchema, disconnectAgentRuntimeSessionSchema, heartbeatAgentRuntimeSessionSchema, reconnectAgentRuntimeSessionSchema } from "../types.js";
 function parseMetadata(raw) {
     try {
@@ -211,7 +212,95 @@ function ensureCurrentSessionInstance(row, externalSessionId) {
     }
     return true;
 }
-function disconnectSupersededSingletonSessions(parsed, sessionId, now) {
+function normalizeIdentityPart(value) {
+    return (value
+        ?.trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9._:]+/g, "_")
+        .replace(/^_+|_+$/g, "") ?? "");
+}
+function shortHash(value) {
+    return createHash("sha1").update(value).digest("hex").slice(0, 12);
+}
+function canonicalRuntimeAgentLabel(provider) {
+    if (provider === "openclaw") {
+        return "Forge OpenClaw";
+    }
+    if (provider === "hermes") {
+        return "Forge Hermes";
+    }
+    return "Forge Codex";
+}
+function canonicalRuntimeDescription(provider) {
+    return `${canonicalRuntimeAgentLabel(provider)} runtime agent with stable Forge identity and linked Kanban user.`;
+}
+function canonicalAgentUserSpec(provider) {
+    if (provider === "openclaw") {
+        return {
+            id: "user_agent_openclaw",
+            handle: "openclaw",
+            displayName: "OpenClaw",
+            description: "OpenClaw runtime actor linked to Forge agent identity and Kanban ownership.",
+            accentColor: "#38bdf8"
+        };
+    }
+    if (provider === "hermes") {
+        return {
+            id: "user_agent_hermes",
+            handle: "hermes",
+            displayName: "Hermes",
+            description: "Hermes runtime actor linked to Forge agent identity and Kanban ownership.",
+            accentColor: "#a78bfa"
+        };
+    }
+    return {
+        id: "user_agent_codex",
+        handle: "codex",
+        displayName: "Codex",
+        description: "Codex runtime actor linked to Forge agent identity and Kanban ownership.",
+        accentColor: "#22c55e"
+    };
+}
+function deriveMachineKey(input) {
+    const explicit = normalizeIdentityPart(input.machineKey);
+    if (explicit) {
+        return explicit;
+    }
+    const source = [
+        normalizeText(input.dataRoot) ?? "",
+        normalizeText(input.baseUrl) ?? "local"
+    ].join("|");
+    return `machine_${shortHash(source)}`;
+}
+function derivePersonaKey(input) {
+    return (normalizeIdentityPart(input.personaKey) ||
+        normalizeIdentityPart(input.agentType) ||
+        "default");
+}
+function deriveAgentIdentityKey(input) {
+    const explicit = normalizeIdentityPart(input.agentIdentityKey);
+    if (explicit) {
+        return explicit;
+    }
+    return `runtime:${input.provider}:${deriveMachineKey(input)}:${derivePersonaKey(input)}`;
+}
+function linkAgentIdentityUsers(agentId, provider, linkedUserIds, now) {
+    const primaryUser = ensureBotUser(canonicalAgentUserSpec(provider));
+    const normalizedUserIds = Array.from(new Set([primaryUser.id, ...linkedUserIds.map((id) => id.trim()).filter(Boolean)]));
+    for (const userId of normalizedUserIds) {
+        if (!getUserById(userId)) {
+            continue;
+        }
+        getDatabase()
+            .prepare(`INSERT INTO agent_identity_users (agent_id, user_id, role, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?)
+         ON CONFLICT(agent_id, user_id) DO UPDATE SET
+           role = excluded.role,
+           updated_at = excluded.updated_at`)
+            .run(agentId, userId, userId === primaryUser.id ? "primary" : "linked", now, now);
+    }
+}
+function disconnectSupersededSingletonSessions(parsed, sessionId, agentId, now) {
     if (!parsed.metadata?.singleton) {
         return;
     }
@@ -224,11 +313,11 @@ function disconnectSupersededSingletonSessions(parsed, sessionId, now) {
          created_at, updated_at
        FROM agent_runtime_sessions
        WHERE provider = ?
-         AND agent_label = ?
+         AND agent_id = ?
          AND coalesce(base_url, '') = coalesce(?, '')
          AND coalesce(data_root, '') = coalesce(?, '')
          AND id <> ?`)
-        .all(parsed.provider, parsed.agentLabel, normalizeText(parsed.baseUrl), normalizeText(parsed.dataRoot), sessionId);
+        .all(parsed.provider, agentId, normalizeText(parsed.baseUrl), normalizeText(parsed.dataRoot), sessionId);
     for (const row of rows) {
         if (row.status === "disconnected" && row.ended_at) {
             continue;
@@ -251,29 +340,45 @@ function disconnectSupersededSingletonSessions(parsed, sessionId, now) {
     }
 }
 function upsertRuntimeAgentIdentity(input) {
+    const identityKey = deriveAgentIdentityKey(input);
+    const machineKey = deriveMachineKey(input);
+    const personaKey = derivePersonaKey(input);
+    const label = canonicalRuntimeAgentLabel(input.provider);
     const existing = getDatabase()
         .prepare(`SELECT id
        FROM agent_identities
-       WHERE lower(label) = lower(?)
+       WHERE identity_key = ?
+          OR (
+            (identity_key IS NULL OR machine_key IS NULL OR machine_key = 'legacy' OR identity_key LIKE 'runtime:%:legacy:%')
+            AND (
+              provider = ?
+              OR lower(agent_type) = lower(?)
+              OR lower(label) = lower(?)
+            )
+          )
        LIMIT 1`)
-        .get(input.agentLabel);
+        .get(identityKey, input.provider, input.provider, label);
     const now = new Date().toISOString();
-    const description = `${input.provider[0].toUpperCase()}${input.provider.slice(1)} runtime session participant registered through Forge.`;
+    const description = canonicalRuntimeDescription(input.provider);
     if (existing) {
         getDatabase()
             .prepare(`UPDATE agent_identities
-         SET agent_type = ?, updated_at = ?
+         SET label = ?, agent_type = ?, identity_key = ?, provider = ?,
+             machine_key = ?, persona_key = ?, description = ?, updated_at = ?
          WHERE id = ?`)
-            .run(input.agentType || input.provider, now, existing.id);
+            .run(label, input.agentType || input.provider, identityKey, input.provider, machineKey, personaKey, description, now, existing.id);
+        linkAgentIdentityUsers(existing.id, input.provider, input.linkedUserIds, now);
         return existing.id;
     }
     const agentId = `agt_${randomUUID().replaceAll("-", "").slice(0, 10)}`;
     getDatabase()
         .prepare(`INSERT INTO agent_identities (
-        id, label, agent_type, trust_level, autonomy_mode, approval_mode,
+        id, label, agent_type, identity_key, provider, machine_key, persona_key,
+        trust_level, autonomy_mode, approval_mode,
         description, created_at, updated_at
-      ) VALUES (?, ?, ?, 'trusted', 'approval_required', 'approval_by_default', ?, ?, ?)`)
-        .run(agentId, input.agentLabel, input.agentType || input.provider, description, now, now);
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, 'trusted', 'approval_required', 'approval_by_default', ?, ?, ?)`)
+        .run(agentId, label, input.agentType || input.provider, identityKey, input.provider, machineKey, personaKey, description, now, now);
+    linkAgentIdentityUsers(agentId, input.provider, input.linkedUserIds, now);
     return agentId;
 }
 function insertSessionEvent(sessionId, input, now = new Date().toISOString()) {
@@ -321,6 +426,7 @@ export function registerAgentRuntimeSession(input) {
     return runInTransaction(() => {
         const now = new Date().toISOString();
         const agentId = upsertRuntimeAgentIdentity(parsed);
+        const agentLabel = canonicalRuntimeAgentLabel(parsed.provider);
         const existing = getSessionRowByCompositeKey(parsed.provider, parsed.sessionKey);
         const sessionId = existing?.id ?? `ags_${randomUUID().replaceAll("-", "").slice(0, 10)}`;
         if (existing) {
@@ -332,7 +438,7 @@ export function registerAgentRuntimeSession(input) {
                last_error = ?, last_seen_at = ?, last_heartbeat_at = ?, started_at = ?,
                ended_at = NULL, metadata_json = ?, updated_at = ?
            WHERE id = ?`)
-                .run(agentId, parsed.agentLabel, parsed.agentType || parsed.provider, parsed.sessionLabel || parsed.sessionKey, parsed.actorLabel, parsed.connectionMode, parsed.status === "error" ? "error" : "connected", normalizeText(parsed.baseUrl), normalizeText(parsed.webUrl), normalizeText(parsed.dataRoot), normalizeText(parsed.externalSessionId), parsed.staleAfterSeconds, normalizeText(parsed.lastError), now, now, now, JSON.stringify(parsed.metadata), now, sessionId);
+                .run(agentId, agentLabel, parsed.agentType || parsed.provider, parsed.sessionLabel || parsed.sessionKey, parsed.actorLabel, parsed.connectionMode, parsed.status === "error" ? "error" : "connected", normalizeText(parsed.baseUrl), normalizeText(parsed.webUrl), normalizeText(parsed.dataRoot), normalizeText(parsed.externalSessionId), parsed.staleAfterSeconds, normalizeText(parsed.lastError), now, now, now, JSON.stringify(parsed.metadata), now, sessionId);
             insertSessionEvent(sessionId, {
                 eventType: "session_registered",
                 title: "Session re-registered",
@@ -349,7 +455,7 @@ export function registerAgentRuntimeSession(input) {
              last_seen_at, last_heartbeat_at, started_at, ended_at, metadata_json,
              created_at, updated_at
            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 0, NULL, ?, ?, ?, ?, NULL, ?, ?, ?)`)
-                .run(sessionId, agentId, parsed.agentLabel, parsed.agentType || parsed.provider, parsed.provider, parsed.sessionKey, parsed.sessionLabel || parsed.sessionKey, parsed.actorLabel, parsed.connectionMode, parsed.status === "error" ? "error" : "connected", normalizeText(parsed.baseUrl), normalizeText(parsed.webUrl), normalizeText(parsed.dataRoot), normalizeText(parsed.externalSessionId), parsed.staleAfterSeconds, normalizeText(parsed.lastError), now, now, now, JSON.stringify(parsed.metadata), now, now);
+                .run(sessionId, agentId, agentLabel, parsed.agentType || parsed.provider, parsed.provider, parsed.sessionKey, parsed.sessionLabel || parsed.sessionKey, parsed.actorLabel, parsed.connectionMode, parsed.status === "error" ? "error" : "connected", normalizeText(parsed.baseUrl), normalizeText(parsed.webUrl), normalizeText(parsed.dataRoot), normalizeText(parsed.externalSessionId), parsed.staleAfterSeconds, normalizeText(parsed.lastError), now, now, now, JSON.stringify(parsed.metadata), now, now);
             insertSessionEvent(sessionId, {
                 eventType: "session_registered",
                 title: "Session registered",
@@ -357,12 +463,12 @@ export function registerAgentRuntimeSession(input) {
                 metadata: parsed.metadata
             }, now);
         }
-        disconnectSupersededSingletonSessions(parsed, sessionId, now);
+        disconnectSupersededSingletonSessions(parsed, sessionId, agentId, now);
         recordActivityEvent({
             entityType: "session",
             entityId: sessionId,
             eventType: "agent_session_registered",
-            title: `Agent session registered: ${parsed.agentLabel}`,
+            title: `Agent session registered: ${agentLabel}`,
             description: `${parsed.provider} registered a live agent session.`,
             actor: parsed.actorLabel,
             source: "agent",

package/dist/server/server/src/repositories/model-settings.js

@@ -47,6 +47,11 @@ export function buildConnectionAgentIdentity(connection) {
         id: connection.agentId,
         label: connection.agentLabel,
         agentType: connection.provider,
+        identityKey: `model:${connection.id}`,
+        provider: null,
+        machineKey: null,
+        personaKey: connection.provider,
+        linkedUsers: [],
         trustLevel: "trusted",
         autonomyMode: "approval_required",
         approvalMode: "approval_by_default",

package/dist/server/server/src/repositories/notes.js

@@ -40,6 +40,9 @@ function normalizeTags(tags) {
         return true;
     });
 }
+function canonicalNoteSourcePath() {
+    return "";
+}
 function parseTagsJson(raw) {
     try {
         const parsed = JSON.parse(raw);
@@ -438,7 +441,7 @@ export function createNote(input, context) {
          source_path, frontmatter_json, revision_hash, last_synced_at, created_at, updated_at
        )
        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
-        .run(id, wikiFields.kind, wikiFields.title, wikiFields.slug, wikiFields.spaceId, wikiFields.parentSlug, wikiFields.indexOrder, wikiFields.showInIndex ? 1 : 0, JSON.stringify(wikiFields.aliases), wikiFields.summary, parsed.contentMarkdown, contentPlain, parsed.author ?? context.actor ?? null, context.source, JSON.stringify(parsed.tags), parsed.destroyAt, parsed.sourcePath, JSON.stringify(parsed.frontmatter), parsed.revisionHash, parsed.lastSyncedAt ?? null, now, now);
+        .run(id, wikiFields.kind, wikiFields.title, wikiFields.slug, wikiFields.spaceId, wikiFields.parentSlug, wikiFields.indexOrder, wikiFields.showInIndex ? 1 : 0, JSON.stringify(wikiFields.aliases), wikiFields.summary, parsed.contentMarkdown, contentPlain, parsed.author ?? context.actor ?? null, context.source, JSON.stringify(parsed.tags), parsed.destroyAt, canonicalNoteSourcePath(), JSON.stringify(parsed.frontmatter), parsed.revisionHash, parsed.lastSyncedAt ?? null, now, now);
     insertLinks(id, parsed.links, now);
     setEntityOwner("note", id, parsed.userId, parsed.author ?? context.actor ?? null);
     clearDeletedEntityRecord("note", id);
@@ -504,7 +507,7 @@ export function updateNote(noteId, input, context) {
         existing
     });
     const nextFrontmatter = patch.frontmatter === undefined ? existing.frontmatter : patch.frontmatter;
-    const nextSourcePath = patch.sourcePath === undefined ? existing.sourcePath : patch.sourcePath;
+    const nextSourcePath = canonicalNoteSourcePath();
     const nextRevisionHash = patch.revisionHash === undefined
         ? existing.revisionHash
         : patch.revisionHash;