npm - forge-openclaw-plugin - Versions diffs - 0.2.15 → 0.2.18 - Mend

forge-openclaw-plugin 0.2.15 → 0.2.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (41) hide show

package/README.md +6 -3
package/dist/assets/{board-C_m78kvK.js → board-2KevHCI0.js} +2 -2
package/dist/assets/{board-C_m78kvK.js.map → board-2KevHCI0.js.map} +1 -1
package/dist/assets/index-CDYW4WDH.js +36 -0
package/dist/assets/index-CDYW4WDH.js.map +1 -0
package/dist/assets/index-yroQr6YZ.css +1 -0
package/dist/assets/{motion-CpZvZumD.js → motion-q19HPmWs.js} +2 -2
package/dist/assets/{motion-CpZvZumD.js.map → motion-q19HPmWs.js.map} +1 -1
package/dist/assets/{table-DtyXTw03.js → table-BDMHBY4a.js} +2 -2
package/dist/assets/{table-DtyXTw03.js.map → table-BDMHBY4a.js.map} +1 -1
package/dist/assets/{ui-BXbpiKyS.js → ui-CQ_AsFs8.js} +2 -2
package/dist/assets/{ui-BXbpiKyS.js.map → ui-CQ_AsFs8.js.map} +1 -1
package/dist/assets/{vendor-QBH6qVEe.js → vendor-5HifrnRK.js} +90 -75
package/dist/assets/{vendor-QBH6qVEe.js.map → vendor-5HifrnRK.js.map} +1 -1
package/dist/assets/{viz-w-IMeueL.js → viz-CQzkRnTu.js} +2 -2
package/dist/assets/{viz-w-IMeueL.js.map → viz-CQzkRnTu.js.map} +1 -1
package/dist/index.html +8 -8
package/dist/openclaw/local-runtime.js +142 -9
package/dist/openclaw/plugin-entry-shared.js +7 -1
package/dist/openclaw/tools.js +15 -0
package/dist/server/app.js +129 -11
package/dist/server/openapi.js +181 -4
package/dist/server/repositories/habits.js +358 -0
package/dist/server/repositories/rewards.js +62 -0
package/dist/server/services/context.js +16 -6
package/dist/server/services/dashboard.js +6 -3
package/dist/server/services/entity-crud.js +23 -1
package/dist/server/services/gamification.js +66 -18
package/dist/server/services/insights.js +2 -1
package/dist/server/services/reviews.js +2 -1
package/dist/server/types.js +140 -1
package/openclaw.plugin.json +1 -1
package/package.json +1 -1
package/server/migrations/003_habits.sql +30 -0
package/server/migrations/004_habit_links.sql +8 -0
package/server/migrations/005_habit_psyche_links.sql +24 -0
package/skills/forge-openclaw/SKILL.md +16 -2
package/skills/forge-openclaw/cron_jobs.md +395 -0
package/dist/assets/index-BWtLtXwb.js +0 -36
package/dist/assets/index-BWtLtXwb.js.map +0 -1
package/dist/assets/index-Dp5GXY_z.css +0 -1

package/dist/index.html CHANGED Viewed

@@ -13,15 +13,15 @@
     />
     <link rel="icon" type="image/png" href="/forge/assets/favicon-BCHm9dUV.ico" />
     <link rel="alternate icon" href="/forge/assets/favicon-BCHm9dUV.ico" />
-    <script type="module" crossorigin src="/forge/assets/index-BWtLtXwb.js"></script>
-    <link rel="modulepreload" crossorigin href="/forge/assets/vendor-QBH6qVEe.js">
-    <link rel="modulepreload" crossorigin href="/forge/assets/motion-CpZvZumD.js">
-    <link rel="modulepreload" crossorigin href="/forge/assets/ui-BXbpiKyS.js">
-    <link rel="modulepreload" crossorigin href="/forge/assets/table-DtyXTw03.js">
-    <link rel="modulepreload" crossorigin href="/forge/assets/viz-w-IMeueL.js">
-    <link rel="modulepreload" crossorigin href="/forge/assets/board-C_m78kvK.js">
+    <script type="module" crossorigin src="/forge/assets/index-CDYW4WDH.js"></script>
+    <link rel="modulepreload" crossorigin href="/forge/assets/vendor-5HifrnRK.js">
+    <link rel="modulepreload" crossorigin href="/forge/assets/motion-q19HPmWs.js">
+    <link rel="modulepreload" crossorigin href="/forge/assets/ui-CQ_AsFs8.js">
+    <link rel="modulepreload" crossorigin href="/forge/assets/table-BDMHBY4a.js">
+    <link rel="modulepreload" crossorigin href="/forge/assets/viz-CQzkRnTu.js">
+    <link rel="modulepreload" crossorigin href="/forge/assets/board-2KevHCI0.js">
     <link rel="stylesheet" crossorigin href="/forge/assets/vendor-CRS-psbw.css">
-    <link rel="stylesheet" crossorigin href="/forge/assets/index-Dp5GXY_z.css">
+    <link rel="stylesheet" crossorigin href="/forge/assets/index-yroQr6YZ.css">
   </head>
   <body class="bg-canvas text-ink antialiased">
     <div id="root"></div>

package/dist/openclaw/local-runtime.js CHANGED Viewed

@@ -47,6 +47,25 @@ function applyPortToConfig(config, port, portSource) {
     config.webAppUrl = buildForgeWebAppUrl(config.origin, port);
     config.portSource = portSource;
 }
+function getExpectedDataRoot(config) {
+    return config.dataRoot.trim().length > 0 ? path.resolve(config.dataRoot) : null;
+}
+function isExpectedDataRoot(expectedDataRoot, actualDataRoot) {
+    if (!expectedDataRoot) {
+        return true;
+    }
+    if (!actualDataRoot) {
+        return false;
+    }
+    return path.resolve(actualDataRoot) === expectedDataRoot;
+}
+function formatRuntimeDataRootMismatch(config, expectedDataRoot, actualDataRoot) {
+    return [
+        `Forge is already responding on ${config.baseUrl}, but it is using storage root ${actualDataRoot ?? "(unknown)"}.`,
+        `The OpenClaw plugin is configured to use ${expectedDataRoot}.`,
+        "Restart the plugin-managed runtime or stop the conflicting Forge server so the configured dataRoot can take over."
+    ].join(" ");
+}
 async function writePreferredPortState(config, port) {
     const statePath = getPreferredPortStatePath(config.origin);
     await mkdir(path.dirname(statePath), { recursive: true });
@@ -272,6 +291,43 @@ async function isForgeHealthy(config, timeoutMs) {
         clearTimeout(timeout);
     }
 }
+async function probeForgeRuntime(config, timeoutMs) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(new URL("/api/v1/health", config.baseUrl), {
+            method: "GET",
+            headers: {
+                accept: "application/json",
+                "x-forge-runtime-probe": "1"
+            },
+            signal: controller.signal
+        });
+        if (!response.ok) {
+            return { healthy: false, pid: null, storageRoot: null, basePath: null };
+        }
+        const payload = (await response.json());
+        return {
+            healthy: true,
+            pid: typeof payload.runtime?.pid === "number" && Number.isFinite(payload.runtime.pid) ? Math.trunc(payload.runtime.pid) : null,
+            storageRoot: typeof payload.runtime?.storageRoot === "string" ? path.resolve(payload.runtime.storageRoot) : null,
+            basePath: typeof payload.runtime?.basePath === "string" ? payload.runtime.basePath : null
+        };
+    }
+    catch {
+        return { healthy: false, pid: null, storageRoot: null, basePath: null };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+async function adoptManagedRuntimeState(config, probe) {
+    if (probe.pid === null || !processExists(probe.pid)) {
+        return false;
+    }
+    await writeRuntimeState(config, probe.pid);
+    return true;
+}
 async function spawnManagedRuntime(config, plan) {
     const isPackagedServer = isPackagedServerPlan(plan);
     const args = isPackagedServer ? [plan.entryFile] : [plan.entryFile, path.join(plan.packageRoot, "server", "src", "index.ts")];
@@ -353,7 +409,13 @@ export async function ensureForgeRuntimeReady(config) {
     if (!isLocalOrigin(config.origin)) {
         return;
     }
-    if (await isForgeHealthy(config, HEALTHCHECK_TIMEOUT_MS)) {
+    const expectedDataRoot = getExpectedDataRoot(config);
+    const initialProbe = await probeForgeRuntime(config, HEALTHCHECK_TIMEOUT_MS);
+    if (initialProbe.healthy && isExpectedDataRoot(expectedDataRoot, initialProbe.storageRoot)) {
+        const existingState = await readRuntimeState(config);
+        if (!existingState) {
+            await adoptManagedRuntimeState(config, initialProbe);
+        }
         return;
     }
     const savedState = await readRuntimeState(config);
@@ -361,12 +423,29 @@ export async function ensureForgeRuntimeReady(config) {
         await clearRuntimeState(config);
     }
     else if (savedState && processExists(savedState.pid)) {
+        if (initialProbe.healthy && !isExpectedDataRoot(expectedDataRoot, initialProbe.storageRoot)) {
+            await stopForgeRuntime(config);
+        }
+        else {
+            try {
+                await waitForRuntime(config, EXISTING_RUNTIME_GRACE_MS, null);
+                return;
+            }
+            catch {
+                await stopForgeRuntime(config);
+            }
+        }
+    }
+    else if (initialProbe.healthy) {
+        if (!isExpectedDataRoot(expectedDataRoot, initialProbe.storageRoot)) {
+            throw new Error(formatRuntimeDataRootMismatch(config, expectedDataRoot, initialProbe.storageRoot));
+        }
         try {
             await waitForRuntime(config, EXISTING_RUNTIME_GRACE_MS, null);
             return;
         }
         catch {
-            await stopForgeRuntime(config);
+            // There is no plugin-managed pid to stop here; fall through into normal startup handling.
         }
     }
     const key = runtimeKey(config);
@@ -378,14 +457,16 @@ export async function ensureForgeRuntimeReady(config) {
         return;
     }
     startupPromise = (async () => {
-        if (await isForgeHealthy(config, HEALTHCHECK_TIMEOUT_MS)) {
+        const probeBeforeStart = await probeForgeRuntime(config, HEALTHCHECK_TIMEOUT_MS);
+        if (probeBeforeStart.healthy && isExpectedDataRoot(expectedDataRoot, probeBeforeStart.storageRoot)) {
             return;
         }
         startupRuntimeKey = runtimeKey(config);
         if (!(await isPortAvailable("127.0.0.1", config.port))) {
             await relocateLocalRuntimePort(config);
             startupRuntimeKey = runtimeKey(config);
-            if (await isForgeHealthy(config, HEALTHCHECK_TIMEOUT_MS)) {
+            const probeAfterRelocation = await probeForgeRuntime(config, HEALTHCHECK_TIMEOUT_MS);
+            if (probeAfterRelocation.healthy && isExpectedDataRoot(expectedDataRoot, probeAfterRelocation.storageRoot)) {
                 return;
             }
         }
@@ -394,6 +475,10 @@ export async function ensureForgeRuntimeReady(config) {
             await spawnManagedRuntime(config, plan);
         }
         await waitForRuntime(config, STARTUP_TIMEOUT_MS, managedRuntimeChild?.pid ?? null);
+        const probeAfterStart = await probeForgeRuntime(config, HEALTHCHECK_TIMEOUT_MS);
+        if (!probeAfterStart.healthy || !isExpectedDataRoot(expectedDataRoot, probeAfterStart.storageRoot)) {
+            throw new Error(formatRuntimeDataRootMismatch(config, expectedDataRoot, probeAfterStart.storageRoot));
+        }
     })().finally(() => {
         startupPromise = null;
         startupRuntimeKey = null;
@@ -411,8 +496,26 @@ export async function startForgeRuntime(config) {
             baseUrl: config.baseUrl
         };
     }
-    const existingState = await readRuntimeState(config);
-    if (!existingState && (await isForgeHealthy(config, HEALTHCHECK_TIMEOUT_MS))) {
+    const expectedDataRoot = getExpectedDataRoot(config);
+    const probe = await probeForgeRuntime(config, HEALTHCHECK_TIMEOUT_MS);
+    let existingState = await readRuntimeState(config);
+    if (!existingState && probe.healthy && isExpectedDataRoot(expectedDataRoot, probe.storageRoot)) {
+        const adopted = await adoptManagedRuntimeState(config, probe);
+        if (adopted) {
+            existingState = await readRuntimeState(config);
+        }
+    }
+    if (probe.healthy && !isExpectedDataRoot(expectedDataRoot, probe.storageRoot)) {
+        return {
+            ok: false,
+            started: false,
+            managed: Boolean(existingState),
+            message: formatRuntimeDataRootMismatch(config, expectedDataRoot, probe.storageRoot),
+            pid: existingState?.pid ?? null,
+            baseUrl: config.baseUrl
+        };
+    }
+    if (!existingState && probe.healthy) {
         return {
             ok: true,
             started: false,
@@ -422,7 +525,7 @@ export async function startForgeRuntime(config) {
             baseUrl: config.baseUrl
         };
     }
-    if (existingState && processExists(existingState.pid) && (await isForgeHealthy(config, HEALTHCHECK_TIMEOUT_MS))) {
+    if (existingState && processExists(existingState.pid) && probe.healthy) {
         return {
             ok: true,
             started: false,
@@ -517,8 +620,16 @@ export async function stopForgeRuntime(config) {
     };
 }
 export async function getForgeRuntimeStatus(config) {
-    const healthy = await isForgeHealthy(config, HEALTHCHECK_TIMEOUT_MS);
-    const state = await readRuntimeState(config);
+    const expectedDataRoot = getExpectedDataRoot(config);
+    const probe = await probeForgeRuntime(config, HEALTHCHECK_TIMEOUT_MS);
+    const healthy = probe.healthy;
+    let state = await readRuntimeState(config);
+    if (!state && healthy && isExpectedDataRoot(expectedDataRoot, probe.storageRoot)) {
+        const adopted = await adoptManagedRuntimeState(config, probe);
+        if (adopted) {
+            state = await readRuntimeState(config);
+        }
+    }
     const pid = state?.pid ?? null;
     const managed = Boolean(state);
     const running = healthy || (pid !== null && processExists(pid));
@@ -548,6 +659,17 @@ export async function getForgeRuntimeStatus(config) {
         };
     }
     if (healthy && managed) {
+        if (!isExpectedDataRoot(expectedDataRoot, probe.storageRoot)) {
+            return {
+                ok: false,
+                running: true,
+                healthy: true,
+                managed: true,
+                message: formatRuntimeDataRootMismatch(config, expectedDataRoot, probe.storageRoot),
+                pid,
+                baseUrl: config.baseUrl
+            };
+        }
         return {
             ok: true,
             running: true,
@@ -559,6 +681,17 @@ export async function getForgeRuntimeStatus(config) {
         };
     }
     if (healthy) {
+        if (!isExpectedDataRoot(expectedDataRoot, probe.storageRoot)) {
+            return {
+                ok: false,
+                running: true,
+                healthy: true,
+                managed: false,
+                message: formatRuntimeDataRootMismatch(config, expectedDataRoot, probe.storageRoot),
+                pid: null,
+                baseUrl: config.baseUrl
+            };
+        }
         return {
             ok: true,
             running: true,

package/dist/openclaw/plugin-entry-shared.js CHANGED Viewed

@@ -40,6 +40,12 @@ function normalizeTimeout(value, fallback) {
     }
     return Math.min(120_000, Math.max(1000, Math.round(value)));
 }
+function normalizeDataRoot(value) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        return "";
+    }
+    return path.resolve(value.trim());
+}
 function isLocalOrigin(origin) {
     try {
         return LOCAL_HOSTNAMES.has(new URL(origin).hostname.toLowerCase());
@@ -80,7 +86,7 @@ export function resolveForgePluginConfig(pluginConfig) {
         baseUrl: buildForgeBaseUrl(origin, port),
         webAppUrl: buildForgeWebAppUrl(origin, port),
         portSource: hasConfiguredPort ? "configured" : preferredPort !== null ? "preferred" : "default",
-        dataRoot: typeof raw.dataRoot === "string" ? raw.dataRoot.trim() : "",
+        dataRoot: normalizeDataRoot(raw.dataRoot),
         apiToken: typeof raw.apiToken === "string" ? raw.apiToken.trim() : "",
         actorLabel: normalizeString(raw.actorLabel, "aurel"),
         timeoutMs: normalizeTimeout(raw.timeoutMs, 15_000)

package/dist/openclaw/tools.js CHANGED Viewed

@@ -238,6 +238,21 @@ export function registerForgePluginTools(api, config) {
         method: "POST",
         path: "/api/v1/entities/restore"
     });
+    registerWriteTool(api, config, {
+        name: "forge_grant_reward_bonus",
+        label: "Forge Grant Reward Bonus",
+        description: "Grant an explicit manual XP bonus or penalty with provenance. Use only for auditable operator judgement beyond the normal task-run and habit reward flows.",
+        parameters: Type.Object({
+            entityType: Type.String({ minLength: 1 }),
+            entityId: Type.String({ minLength: 1 }),
+            deltaXp: Type.Number(),
+            reasonTitle: Type.String({ minLength: 1 }),
+            reasonSummary: optionalString(),
+            metadata: Type.Optional(Type.Record(Type.String(), Type.Any()))
+        }),
+        method: "POST",
+        path: "/api/v1/rewards/bonus"
+    });
     registerWriteTool(api, config, {
         name: "forge_post_insight",
         label: "Forge Post Insight",

package/dist/server/app.js CHANGED Viewed

@@ -7,6 +7,7 @@ import { listActivityEvents, listActivityEventsForTask, removeActivityEvent } fr
 import { approveApprovalRequest, createAgentAction, createInsight, createInsightFeedback, deleteInsight, getInsightById, listAgentActions, listApprovalRequests, listInsights, rejectApprovalRequest, updateInsight } from "./repositories/collaboration.js";
 import { listEventLog } from "./repositories/event-log.js";
 import { createGoal, getGoalById, listGoals, updateGoal } from "./repositories/goals.js";
+import { createHabit, createHabitCheckIn, getHabitById, listHabits, updateHabit } from "./repositories/habits.js";
 import { listDomains } from "./repositories/domains.js";
 import { buildNotesSummaryByEntity, createNote, getNoteById, listNotes, updateNote } from "./repositories/notes.js";
 import { createBehavior, createBehaviorPattern, createBeliefEntry, createEmotionDefinition, createEventType, createModeGuideSession, createModeProfile, createPsycheValue, createTriggerReport, getBehaviorById, getBehaviorPatternById, getBeliefEntryById, getEmotionDefinitionById, getEventTypeById, getModeGuideSessionById, getModeProfileById, getPsycheValueById, getTriggerReportById, listBehaviors, listBehaviorPatterns, listBeliefEntries, listEmotionDefinitions, listEventTypes, listModeGuideSessions, listModeProfiles, listPsycheValues, listSchemaCatalog, listTriggerReports, updateBehavior, updateBehaviorPattern, updateBeliefEntry, updateEmotionDefinition, updateEventType, updateModeGuideSession, updateModeProfile, updatePsycheValue, updateTriggerReport } from "./repositories/psyche.js";
@@ -27,7 +28,7 @@ import { getWeeklyReviewPayload } from "./services/reviews.js";
 import { createTaskRunWatchdog } from "./services/task-run-watchdog.js";
 import { suggestTags } from "./services/tagging.js";
 import { PSYCHE_ENTITY_TYPES, createBehaviorSchema, createBeliefEntrySchema, createBehaviorPatternSchema, createEmotionDefinitionSchema, createEventTypeSchema, createModeGuideSessionSchema, createModeProfileSchema, createPsycheValueSchema, createTriggerReportSchema, updateBehaviorSchema, updateBeliefEntrySchema, updateBehaviorPatternSchema, updateEmotionDefinitionSchema, updateEventTypeSchema, updateModeGuideSessionSchema, updateModeProfileSchema, updatePsycheValueSchema, updateTriggerReportSchema } from "./psyche-types.js";
-import { activityListQuerySchema, activitySourceSchema, createAgentActionSchema, createAgentTokenSchema, batchCreateEntitiesSchema, batchDeleteEntitiesSchema, batchRestoreEntitiesSchema, batchSearchEntitiesSchema, batchUpdateEntitiesSchema, createGoalSchema, createInsightFeedbackSchema, createInsightSchema, createNoteSchema, createProjectSchema, createManualRewardGrantSchema, createSessionEventSchema, createTagSchema, notesListQuerySchema, updateTagSchema, createTaskSchema, eventsListQuerySchema, operatorLogWorkSchema, projectBoardPayloadSchema, projectListQuerySchema, entityDeleteQuerySchema, removeActivityEventSchema, resolveApprovalRequestSchema, rewardsLedgerQuerySchema, taskContextPayloadSchema, taskRunClaimSchema, taskRunFocusSchema, taskRunFinishSchema, taskRunHeartbeatSchema, taskRunListQuerySchema, taskListQuerySchema, tagSuggestionRequestSchema, uncompleteTaskSchema, updateSettingsSchema, updateGoalSchema, updateInsightSchema, updateNoteSchema, updateProjectSchema, updateRewardRuleSchema, updateTaskSchema } from "./types.js";
+import { activityListQuerySchema, activitySourceSchema, createAgentActionSchema, createAgentTokenSchema, batchCreateEntitiesSchema, batchDeleteEntitiesSchema, batchRestoreEntitiesSchema, batchSearchEntitiesSchema, batchUpdateEntitiesSchema, createGoalSchema, createInsightFeedbackSchema, createInsightSchema, createNoteSchema, createProjectSchema, createManualRewardGrantSchema, createHabitCheckInSchema, createHabitSchema, createSessionEventSchema, createTagSchema, notesListQuerySchema, updateTagSchema, createTaskSchema, eventsListQuerySchema, operatorLogWorkSchema, projectBoardPayloadSchema, projectListQuerySchema, entityDeleteQuerySchema, removeActivityEventSchema, resolveApprovalRequestSchema, rewardsLedgerQuerySchema, habitListQuerySchema, taskContextPayloadSchema, taskRunClaimSchema, taskRunFocusSchema, taskRunFinishSchema, taskRunHeartbeatSchema, taskRunListQuerySchema, taskListQuerySchema, tagSuggestionRequestSchema, uncompleteTaskSchema, updateSettingsSchema, updateGoalSchema, updateHabitSchema, updateInsightSchema, updateNoteSchema, updateProjectSchema, updateRewardRuleSchema, updateTaskSchema } from "./types.js";
 import { buildOpenApiDocument } from "./openapi.js";
 import { registerWebRoutes } from "./web.js";
 import { createManagerRuntime } from "./managers/runtime.js";
@@ -186,6 +187,39 @@ const AGENT_ONBOARDING_ENTITY_CATALOG = [
             { name: "notes", type: "Array<{ contentMarkdown, author?, links? }>", required: false, description: "Optional nested notes that will auto-link to the new task.", defaultValue: [] }
         ]
     },
+    {
+        entityType: "habit",
+        purpose: "A recurring commitment or recurring slip with explicit cadence, graph links, and XP consequences.",
+        minimumCreateFields: ["title"],
+        relationshipRules: [
+            "Habits can link directly to goals, projects, tasks, values, patterns, behaviors, beliefs, modes, and trigger reports.",
+            "Habits are recurring records, not task variants, and they participate in search, notes, delete/restore, and XP.",
+            "linkedBehaviorId remains a compatibility alias; linkedBehaviorIds is the canonical array form."
+        ],
+        searchHints: ["Search by title before creating a duplicate habit.", "Use linkedTo when the habit should already be attached to a goal, project, task, or Psyche entity."],
+        examples: ['{"title":"Morning training","frequency":"daily","polarity":"positive","linkedGoalIds":["goal_train_body"],"linkedValueIds":["value_steadiness"],"linkedBehaviorIds":["behavior_regulating_walk"]}'],
+        fieldGuide: [
+            { name: "title", type: "string", required: true, description: "Concrete recurring behavior label." },
+            { name: "description", type: "string", required: false, description: "What counts as success or failure for this habit.", defaultValue: "" },
+            { name: "status", type: "active|paused|archived", required: false, description: "Lifecycle state.", enumValues: ["active", "paused", "archived"], defaultValue: "active" },
+            { name: "polarity", type: "positive|negative", required: false, description: "Whether doing the behavior is aligned or misaligned.", enumValues: ["positive", "negative"], defaultValue: "positive" },
+            { name: "frequency", type: "daily|weekly", required: false, description: "Recurrence cadence.", enumValues: ["daily", "weekly"], defaultValue: "daily" },
+            { name: "targetCount", type: "integer", required: false, description: "How many repetitions define the cadence window.", defaultValue: 1 },
+            { name: "weekDays", type: "integer[]", required: false, description: "Weekday numbers for weekly habits where Monday is 1 and Sunday is 0.", defaultValue: [] },
+            { name: "linkedGoalIds", type: "string[]", required: false, description: "Linked goal ids.", defaultValue: [] },
+            { name: "linkedProjectIds", type: "string[]", required: false, description: "Linked project ids.", defaultValue: [] },
+            { name: "linkedTaskIds", type: "string[]", required: false, description: "Linked task ids.", defaultValue: [] },
+            { name: "linkedValueIds", type: "string[]", required: false, description: "Linked value ids.", defaultValue: [] },
+            { name: "linkedPatternIds", type: "string[]", required: false, description: "Linked pattern ids.", defaultValue: [] },
+            { name: "linkedBehaviorIds", type: "string[]", required: false, description: "Canonical linked behavior ids.", defaultValue: [] },
+            { name: "linkedBehaviorId", type: "string|null", required: false, description: "Compatibility alias for the first linked behavior id.", defaultValue: null, nullable: true },
+            { name: "linkedBeliefIds", type: "string[]", required: false, description: "Linked belief ids.", defaultValue: [] },
+            { name: "linkedModeIds", type: "string[]", required: false, description: "Linked mode ids.", defaultValue: [] },
+            { name: "linkedReportIds", type: "string[]", required: false, description: "Linked trigger report ids.", defaultValue: [] },
+            { name: "rewardXp", type: "integer", required: false, description: "XP granted on aligned check-ins.", defaultValue: 12 },
+            { name: "penaltyXp", type: "integer", required: false, description: "XP removed on misaligned check-ins.", defaultValue: 8 }
+        ]
+    },
     {
         entityType: "note",
         purpose: "A Markdown note that can link to one or many Forge entities.",
@@ -594,6 +628,15 @@ const AGENT_ONBOARDING_TOOL_INPUT_CATALOG = [
         notes: ["Restore only works for soft-deleted entities."],
         example: '{"operations":[{"entityType":"goal","id":"goal_123","clientRef":"goal-restore-1"}]}'
     },
+    {
+        toolName: "forge_grant_reward_bonus",
+        summary: "Grant an explicit manual XP bonus or penalty with clear provenance.",
+        whenToUse: "Use when the user or operator explicitly wants an auditable reward adjustment beyond the automatic task and habit reward paths.",
+        inputShape: "{ entityType: RewardableEntityType, entityId: string, deltaXp: integer, reasonTitle: string, reasonSummary?: string, metadata?: object }",
+        requiredFields: ["entityType", "entityId", "deltaXp", "reasonTitle"],
+        notes: ["Requires rewards.manage and write scopes.", "Use this for explicit operator judgement, not as a substitute for normal task_run or habit check-in rewards."],
+        example: '{"entityType":"habit","entityId":"habit_morning_training","deltaXp":18,"reasonTitle":"Operator bonus","reasonSummary":"Stayed with the habit through unusual travel friction.","metadata":{"manual":true,"source":"agent"}}'
+    },
     {
         toolName: "forge_post_insight",
         summary: "Store an agent-authored insight.",
@@ -736,6 +779,7 @@ function buildAgentOnboardingPayload(request) {
             "Goals are the top-level strategic layer.",
             "Projects belong to one goal through goalId.",
             "Tasks can belong to a goal, a project, both, or neither.",
+            "Habits are recurring records that can connect directly to goals, projects, tasks, and durable Psyche entities.",
             "Task runs represent live work sessions on tasks and are separate from task status.",
             "Notes can link to one or many entities and are the canonical place for Markdown progress context or close-out evidence.",
             "Psyche values can link to goals, projects, and tasks.",
@@ -771,6 +815,7 @@ function buildAgentOnboardingPayload(request) {
                 "forge_delete_entities",
                 "forge_restore_entities"
             ],
+            rewardWorkflow: ["forge_grant_reward_bonus"],
             workWorkflow: [
                 "forge_log_work",
                 "forge_start_task_run",
@@ -955,7 +1000,17 @@ function buildHealthPayload(taskRunWatchdog, extras = {}) {
         ...extras
     };
 }
+function shouldIncludeRuntimeProbe(headers) {
+    const probeHeader = headers["x-forge-runtime-probe"];
+    if (Array.isArray(probeHeader)) {
+        return probeHeader.some((value) => typeof value === "string" && value.trim() === "1");
+    }
+    return typeof probeHeader === "string" && probeHeader.trim() === "1";
+}
 function buildV1Context() {
+    const goals = listGoals();
+    const tasks = listTasks();
+    const habits = listHabits();
     return {
         meta: {
             apiVersion: "v1",
@@ -964,15 +1019,16 @@ function buildV1Context() {
             backend: "forge-node-runtime",
             mode: "transitional-node"
         },
-        metrics: buildGamificationProfile(listGoals(), listTasks()),
+        metrics: buildGamificationProfile(goals, tasks, habits),
         dashboard: getDashboard(),
         overview: getOverviewContext(),
         today: getTodayContext(),
         risk: getRiskContext(),
-        goals: listGoals(),
+        goals,
         projects: listProjectSummaries(),
         tags: listTags(),
-        tasks: listTasks(),
+        tasks,
+        habits,
         activeTaskRuns: listTaskRuns({ active: true, limit: 25 }),
         activity: listActivityEvents({ limit: 25 })
     };
@@ -980,8 +1036,9 @@ function buildV1Context() {
 function buildXpMetricsPayload() {
     const goals = listGoals();
     const tasks = listTasks();
+    const habits = listHabits();
     const rules = listRewardRules();
-    const gamificationOverview = buildGamificationOverview(goals, tasks);
+    const gamificationOverview = buildGamificationOverview(goals, tasks, habits);
     const dailyAmbientCap = rules
         .filter((rule) => rule.family === "ambient")
         .reduce((max, rule) => Math.max(max, Number(rule.config.dailyCap ?? 0)), 0) || 12;
@@ -989,7 +1046,7 @@ function buildXpMetricsPayload() {
         profile: gamificationOverview.profile,
         achievements: gamificationOverview.achievements,
         milestoneRewards: gamificationOverview.milestoneRewards,
-        momentumPulse: buildXpMomentumPulse(goals, tasks),
+        momentumPulse: buildXpMomentumPulse(goals, tasks, habits),
         recentLedger: listRewardLedger({ limit: 25 }),
         rules,
         dailyAmbientXp: getDailyAmbientXp(new Date().toISOString().slice(0, 10)),
@@ -998,6 +1055,7 @@ function buildXpMetricsPayload() {
 }
 function buildOperatorContext() {
     const tasks = listTasks();
+    const dueHabits = listHabits({ dueToday: true }).slice(0, 12);
     const activeProjects = listProjectSummaries({ status: "active" }).filter((project) => project.activeTaskCount > 0 || project.completedTaskCount > 0);
     const focusTasks = tasks.filter((task) => task.status === "focus" || task.status === "in_progress");
     const recommendedNextTask = focusTasks[0] ??
@@ -1008,6 +1066,7 @@ function buildOperatorContext() {
         generatedAt: new Date().toISOString(),
         activeProjects: activeProjects.slice(0, 8),
         focusTasks: focusTasks.slice(0, 12),
+        dueHabits,
         currentBoard: {
             backlog: tasks.filter((task) => task.status === "backlog").slice(0, 20),
             focus: tasks.filter((task) => task.status === "focus").slice(0, 20),
@@ -1231,9 +1290,18 @@ export async function buildServer(options = {}) {
         return context;
     };
     app.get("/api/health", async () => buildHealthPayload(taskRunWatchdog));
-    app.get("/api/v1/health", async () => buildHealthPayload(taskRunWatchdog, {
+    app.get("/api/v1/health", async (request) => buildHealthPayload(taskRunWatchdog, {
         apiVersion: "v1",
-        backend: "forge-node-runtime"
+        backend: "forge-node-runtime",
+        ...(shouldIncludeRuntimeProbe(request.headers)
+            ? {
+                runtime: {
+                    pid: process.pid,
+                    storageRoot: runtimeConfig.dataRoot ?? process.cwd(),
+                    basePath: runtimeConfig.basePath
+                }
+            }
+            : {})
     }));
     app.get("/api/v1/auth/operator-session", async (request, reply) => ({
         session: managers.session.ensureLocalOperatorSession(request.headers, reply)
@@ -1721,6 +1789,19 @@ export async function buildServer(options = {}) {
         const query = taskListQuerySchema.parse(request.query ?? {});
         return { tasks: listTasks(query) };
     });
+    app.get("/api/v1/habits", async (request) => {
+        const query = habitListQuerySchema.parse(request.query ?? {});
+        return { habits: listHabits(query) };
+    });
+    app.get("/api/v1/habits/:id", async (request, reply) => {
+        const { id } = request.params;
+        const habit = getHabitById(id);
+        if (!habit) {
+            reply.code(404);
+            return { error: "Habit not found" };
+        }
+        return { habit };
+    });
     app.get("/api/v1/projects/:id", async (request, reply) => {
         const { id } = request.params;
         const project = listProjectSummaries().find((entry) => entry.id === id);
@@ -1764,7 +1845,7 @@ export async function buildServer(options = {}) {
         return { event };
     });
     app.get("/api/v1/metrics", async () => ({
-        metrics: buildGamificationOverview(listGoals(), listTasks())
+        metrics: buildGamificationOverview(listGoals(), listTasks(), listHabits())
     }));
     app.get("/api/v1/metrics/xp", async () => ({
         metrics: buildXpMetricsPayload()
@@ -1944,6 +2025,12 @@ export async function buildServer(options = {}) {
         reply.code(201);
         return { project };
     });
+    app.post("/api/v1/habits", async (request, reply) => {
+        const auth = requireScopedAccess(request.headers, ["write"], { route: "/api/v1/habits" });
+        const habit = createHabit(createHabitSchema.parse(request.body ?? {}), toActivityContext(auth));
+        reply.code(201);
+        return { habit };
+    });
     app.patch("/api/v1/projects/:id", async (request, reply) => {
         const auth = requireScopedAccess(request.headers, ["write"], { route: "/api/v1/projects/:id" });
         const { id } = request.params;
@@ -1964,6 +2051,36 @@ export async function buildServer(options = {}) {
         }
         return { project };
     });
+    app.patch("/api/v1/habits/:id", async (request, reply) => {
+        const auth = requireScopedAccess(request.headers, ["write"], { route: "/api/v1/habits/:id" });
+        const { id } = request.params;
+        const habit = updateHabit(id, updateHabitSchema.parse(request.body ?? {}), toActivityContext(auth));
+        if (!habit) {
+            reply.code(404);
+            return { error: "Habit not found" };
+        }
+        return { habit };
+    });
+    app.delete("/api/v1/habits/:id", async (request, reply) => {
+        const auth = requireScopedAccess(request.headers, ["write"], { route: "/api/v1/habits/:id" });
+        const { id } = request.params;
+        const habit = deleteEntity("habit", id, entityDeleteQuerySchema.parse(request.query ?? {}), toActivityContext(auth));
+        if (!habit) {
+            reply.code(404);
+            return { error: "Habit not found" };
+        }
+        return { habit };
+    });
+    app.post("/api/v1/habits/:id/check-ins", async (request, reply) => {
+        const auth = requireScopedAccess(request.headers, ["write"], { route: "/api/v1/habits/:id/check-ins" });
+        const { id } = request.params;
+        const habit = createHabitCheckIn(id, createHabitCheckInSchema.parse(request.body ?? {}), toActivityContext(auth));
+        if (!habit) {
+            reply.code(404);
+            return { error: "Habit not found" };
+        }
+        return { habit, metrics: buildXpMetricsPayload() };
+    });
     app.patch("/api/v1/settings", async (request) => {
         const auth = requireScopedAccess(request.headers, ["write"], { route: "/api/v1/settings" });
         return {
@@ -2072,7 +2189,7 @@ export async function buildServer(options = {}) {
     app.get("/api/metrics", async (_request, reply) => {
         markCompatibilityRoute(reply);
         return {
-            metrics: buildGamificationProfile(listGoals(), listTasks())
+            metrics: buildGamificationProfile(listGoals(), listTasks(), listHabits())
         };
     });
     app.get("/api/task-runs", async (request, reply) => {
@@ -2102,7 +2219,7 @@ export async function buildServer(options = {}) {
         markCompatibilityRoute(reply);
         const query = taskListQuerySchema.parse(request.query ?? {});
         return {
-            metrics: buildGamificationProfile(listGoals(), listTasks()),
+            metrics: buildGamificationProfile(listGoals(), listTasks(), listHabits()),
             dashboard: getDashboard(),
             overview: getOverviewContext(),
             today: getTodayContext(),
@@ -2111,6 +2228,7 @@ export async function buildServer(options = {}) {
             projects: listProjectSummaries(),
             tags: listTags(),
             tasks: listTasks(query),
+            habits: listHabits(),
             activeTaskRuns: listTaskRuns({ active: true, limit: 25 }),
             activity: listActivityEvents({ limit: 25 })
         };