march-cli 0.1.37 → 0.1.39

package/src/cli/workspace/project-runtime.mjs

@@ -0,0 +1,94 @@
+import { existsSync, mkdirSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { createRuntimeRunner } from "../startup/create-runtime-runner.mjs";
+import { createCliShellRuntime } from "../../shell/cli-runtime.mjs";
+import { createMarchAuthStorage } from "../../auth/storage.mjs";
+import { discoverProjectExtensionPaths } from "../../extensions/discovery.mjs";
+import { loadProjectLifecycleHookManifests } from "../../extensions/lifecycle-manifest.mjs";
+import { loadKeybindings } from "../input/keybindings.mjs";
+import { loadPromptTemplates } from "../input/prompt-templates.mjs";
+import { loadOrCreateProjectId } from "../../workspace/project-id.mjs";
+import { syncRuntimeSessionStateFromRunner } from "./runtime-session-state.mjs";
+
+export async function createWorkspaceProjectRuntime({
+  project,
+  args,
+  config,
+  stateRoot,
+  memoryRoot,
+  profilePaths,
+  createMemoryStore,
+  provider,
+  serviceTier,
+  model,
+  remoteMemorySources,
+  createUi,
+  refreshStatusBar,
+  onNotificationActivation = null,
+}) {
+  const cwd = project.rootPath;
+  const projectMarchDir = resolve(cwd, ".march");
+  if (!existsSync(projectMarchDir)) mkdirSync(projectMarchDir, { recursive: true });
+
+  const authConfig = createMarchAuthStorage({ provider: provider ?? "deepseek", providers: config.providers, cwd });
+  if (!authConfig.hasAuth) throw new Error(`no providers configured for project: ${cwd}`);
+
+  const namespace = loadOrCreateProjectId(projectMarchDir);
+  const extensionPaths = [
+    ...discoverProjectExtensionPaths(cwd),
+    ...args.extensions.map((extensionPath) => resolve(cwd, extensionPath)),
+  ];
+  const lifecycleManifests = loadProjectLifecycleHookManifests(cwd);
+  const keybindingConfig = loadKeybindings(cwd);
+  const promptTemplateConfig = loadPromptTemplates(cwd);
+  const projectShellRuntime = args.shellRuntime ? createCliShellRuntime({ cwd }) : null;
+  const sessionsRoot = join(projectMarchDir, "sessions");
+  const sessionState = { sessionId: Date.now().toString(36), sessionDir: null };
+  sessionState.sessionDir = join(sessionsRoot, sessionState.sessionId);
+  const contextDumpRoot = resolve(projectMarchDir, "context-dumps", sessionState.sessionId);
+  const memoryStore = createMemoryStore();
+  const ui = createUi(sessionState);
+  const runner = await createRuntimeRunner({
+    runnerOptions: {
+      cwd,
+      modelId: model,
+      provider,
+      serviceTier,
+      providers: config.providers,
+      config,
+      stateRoot,
+      memoryRoot,
+      profilePaths,
+      namespace,
+      projectMarchDir,
+      extensionPaths,
+      shellRuntime: Boolean(projectShellRuntime),
+      lifecycleHooks: lifecycleManifests.hooks,
+      lifecycleDiagnostics: lifecycleManifests.diagnostics,
+      modelContextDumper: { enabled: args.dumpContext, rootDir: contextDumpRoot },
+      remoteMemorySources,
+      notificationContext: { projectId: project.projectId },
+    },
+    ui,
+    shellRuntime: projectShellRuntime,
+    refreshStatusBar,
+    onNotificationActivation,
+  });
+  syncRuntimeSessionStateFromRunner(sessionState, runner, sessionsRoot);
+
+  return {
+    project,
+    cwd,
+    currentProject: basename(cwd),
+    runner,
+    ui,
+    memoryStore,
+    sessionState,
+    sessionsRoot,
+    projectMarchDir,
+    extensionPaths,
+    keybindingConfig,
+    promptTemplateConfig,
+    contextDumpRoot,
+  };
+}

package/src/cli/workspace/runtime-session-state.mjs

@@ -0,0 +1,9 @@
+import { join } from "node:path";
+
+export function syncRuntimeSessionStateFromRunner(sessionState, runner, sessionsRoot) {
+  const sessionId = runner?.getSessionStats?.()?.sessionId ?? null;
+  if (!sessionState || !sessionId) return null;
+  sessionState.sessionId = sessionId;
+  sessionState.sessionDir = sessionsRoot ? join(sessionsRoot, sessionId) : sessionState.sessionDir;
+  return sessionState;
+}

package/src/config/features.mjs

@@ -7,7 +7,6 @@ const DEFAULTS = Object.freeze({
   "experimental.web_search": true,
   "experimental.web_fetch": true,
   "experimental.shell": true,
-  "experimental.permissions": true,
   "ui.markdown_rendering": false,
   "ui.tool_expand_per_card": false,
   "agent.plan_mode": false,

package/src/extensions/lifecycle-adapter.mjs

@@ -7,7 +7,7 @@ export const MARCH_LIFECYCLE_LAYERS = Object.freeze([
   {
     name: "march-agent-runtime",
     owner: "March runner",
-    effects: Object.freeze(["read-session-ref", "read-sidecar-metadata", "read-runtime-state"]),
+    effects: Object.freeze(["read-session-ref", "read-session-state", "read-runtime-state"]),
   },
   {
     name: "march-collaboration",
@@ -24,7 +24,7 @@ export const DEFAULT_MARCH_HOOK_POLICY = Object.freeze({
     "read-agent-ref",
     "read-workspace-ref",
     "read-session-ref",
-    "read-sidecar-metadata",
+    "read-session-state",
     "read-diff-metadata",
     "read-runtime-diagnostics",
     "write-diagnostics",
@@ -109,7 +109,7 @@ export function createMarchLifecycleAdapter({
             type: "info",
             message: hooks.size === 0
               ? "March lifecycle hook adapter is read-only; no March hooks are registered."
-              : "March lifecycle hook adapter is read-only; registered hooks are permission-gated.",
+              : "March lifecycle hook adapter is read-only; registered hooks are policy-gated.",
           },
           ...adapterDiagnostics,
           ...getRuntimeDiagnostics(),

package/src/main.mjs

@@ -1,3 +1,4 @@
+import { createRequire } from "node:module";
 import { homedir } from "node:os";
 import { join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -13,6 +14,8 @@ import { installNetworkEnvironment } from "./network/environment.mjs";
 import { runEarlyCliCommand } from "./cli/startup/early-command.mjs";
 import { maybeRunGatewayDaemonCommand } from "./cli/startup/gateway-daemon-command.mjs";
 
+const { version: packageVersion } = createRequire(import.meta.url)("../package.json");
+
 export async function run(argv) {
   const cwd = process.cwd();
   loadDotEnv(cwd);
@@ -23,6 +26,10 @@ export async function run(argv) {
     showHelp();
     return 0;
   }
+  if (args.version) {
+    process.stdout.write(`${packageVersion}\n`);
+    return 0;
+  }
 
   const config = loadConfig(cwd);
   const stateRoot = join(homedir(), ".march");
@@ -67,7 +74,6 @@ export async function run(argv) {
   }
 
   const dumpContextPath = args.dumpContext ? relative(cwd, app.contextDumpRoot) : null;
-  if (app.startupResume.transcriptTurns?.length > 0) app.ui.restoreTranscript?.(app.startupResume.transcriptTurns);
   for (const line of formatStartupBanner({ cwd, modelId: app.runner.engine.modelId, thinkingLevel: app.runner.engine.thinkingLevel, mode: app.modeState.get(), dumpContextPath })) app.ui.writeln(line);
   try {
     await runInteractiveRepl({
@@ -77,6 +83,10 @@ export async function run(argv) {
       runner: app.runner,
       memoryStore: app.memoryStore,
       currentProject: app.currentProject,
+      currentProjectInfo: app.currentProjectInfo,
+      workspaceSupervisor: app.workspaceSupervisor,
+      workspaceOutputRouter: app.workspaceOutputRouter,
+      stateRoot,
       sessionState: app.sessionState,
       sessionsRoot: app.sessionsRoot,
       projectMarchDir: app.projectMarchDir,

package/src/notification/desktop-notifier.mjs

@@ -12,6 +12,7 @@ export function createDesktopTurnNotifier({
   writeBell = () => process.stdout.write("\x07"),
   toastNotifier = nodeNotifier,
   config = {},
+  onActivation = null,
 } = {}) {
   const channels = resolveNotificationChannels(config);
   const minDurationMs = normalizeNonNegativeInteger(config.minDurationMs, 0);
@@ -31,7 +32,7 @@ export function createDesktopTurnNotifier({
       if (channels.desktop) {
         results.push({
           channel: "desktop",
-          ...(await sendDesktopNotification({ platform, spawnProcess, toastNotifier, ...payload })),
+          ...(await sendDesktopNotification({ platform, spawnProcess, toastNotifier, onActivation, activation: normalizedEvent.activation, ...payload })),
         });
       }
       if (channels.bell) results.push({ channel: "bell", ...sendBellNotification({ writeBell }) });
@@ -52,14 +53,14 @@ export function createDesktopTurnNotifier({
   };
 }
 
-export async function sendDesktopNotification({ platform = process.platform, spawnProcess = spawn, toastNotifier = nodeNotifier, title, message, iconPath = DEFAULT_NOTIFICATION_ICON_PATH, sound = true }) {
+export async function sendDesktopNotification({ platform = process.platform, spawnProcess = spawn, toastNotifier = nodeNotifier, title, message, iconPath = DEFAULT_NOTIFICATION_ICON_PATH, sound = true, activation = null, onActivation = null }) {
   if (platform !== "win32") return { ok: false, reason: "unsupported-platform" };
 
   const safeTitle = normalizeNotificationText(title) || "March";
   const safeMessage = normalizeNotificationText(message) || "Turn finished";
 
   try {
-    const toastResult = await sendWindowsToastNotification({ toastNotifier, title: safeTitle, message: safeMessage, iconPath, sound });
+    const toastResult = await sendWindowsToastNotification({ toastNotifier, title: safeTitle, message: safeMessage, iconPath, sound, activation, onActivation });
     if (toastResult.ok) return { ok: true };
 
     const script = buildWindowsNotificationScript({ title: safeTitle, message: safeMessage, iconPath });
@@ -140,18 +141,19 @@ export function buildWindowsNotificationScript({ title, message, timeoutMs = DEF
   return buildWindowsBalloonScript({ title, message, timeoutMs, iconPath });
 }
 
-export function buildWindowsToastOptions({ title, message, iconPath = DEFAULT_NOTIFICATION_ICON_PATH, sound = true }) {
+export function buildWindowsToastOptions({ title, message, iconPath = DEFAULT_NOTIFICATION_ICON_PATH, sound = true, activation = null }) {
   return {
     title,
     message,
     icon: iconPath,
     appID: "March",
     sound,
-    wait: false,
+    wait: Boolean(activation),
+    ...(activation ? { activation } : {}),
   };
 }
 
-function sendWindowsToastNotification({ toastNotifier = nodeNotifier, title, message, iconPath, sound }) {
+function sendWindowsToastNotification({ toastNotifier = nodeNotifier, title, message, iconPath, sound, activation = null, onActivation = null }) {
   return new Promise((resolve) => {
     const notify = toastNotifier?.notify;
     if (typeof notify !== "function") {
@@ -161,12 +163,13 @@ function sendWindowsToastNotification({ toastNotifier = nodeNotifier, title, mes
 
     let settled = false;
     const timeout = setTimeout(() => finish({ ok: false, reason: "toast-timeout" }), DEFAULT_BALLOON_TIMEOUT_MS + 5000);
-    notify.call(toastNotifier, buildWindowsToastOptions({ title, message, iconPath, sound }), (err) => {
+    notify.call(toastNotifier, buildWindowsToastOptions({ title, message, iconPath, sound, activation }), (err, response, metadata) => {
       if (err) {
         finish({ ok: false, reason: err?.message ?? String(err) });
         return;
       }
-      finish({ ok: true });
+      if (isNotificationActivation(response, metadata)) onActivation?.(activation);
+      finish({ ok: true, activated: isNotificationActivation(response, metadata) });
     });
 
     function finish(result) {
@@ -178,6 +181,11 @@ function sendWindowsToastNotification({ toastNotifier = nodeNotifier, title, mes
   });
 }
 
+function isNotificationActivation(response, metadata) {
+  const text = `${response ?? ""} ${metadata?.activationType ?? ""} ${metadata?.activationKind ?? ""}`.toLowerCase();
+  return /activate|click|contentsclicked|buttonclicked/.test(text);
+}
+
 function resolveNotificationChannels(config) {
   return {
     desktop: config.desktop !== false,

package/src/session/sidecar-sync.mjs

@@ -1,19 +1,5 @@
-import { savePiSessionSidecar } from "./sidecar.mjs";
+import { syncMarchSessionState } from "./state/march-session-sync.mjs";
 
-export function syncPiSessionSidecar({ enabled = false, projectMarchDir, engine, sessionStats, metadata = {} }) {
-  if (!enabled || !projectMarchDir || !sessionStats?.persisted || !sessionStats.sessionFile) {
-    return null;
-  }
-
-  return savePiSessionSidecar({
-    projectMarchDir,
-    sessionRef: sessionStats.sessionFile,
-    engine,
-    metadata: {
-      sessionId: sessionStats.sessionId,
-      sessionFile: sessionStats.sessionFile,
-      runtimeHost: Boolean(sessionStats.runtimeHost),
-      ...metadata,
-    },
-  });
+export function syncPiSessionSidecar(options) {
+  return syncMarchSessionState(options);
 }

package/src/session/sidecar.mjs

@@ -1,69 +1,68 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { basename, join } from "node:path";
+import {
+  captureMarchSessionState,
+  getLegacyPiSidecarDir,
+  getLegacyPiSidecarPath,
+  loadMarchSessionStateForPiBackend,
+  loadLegacyPiSidecar,
+  saveMarchSessionStateValue,
+} from "./state/march-session-state.mjs";
 
 export const PI_SIDECAR_VERSION = 1;
 
 export function getPiSidecarDir(projectMarchDir) {
-  return join(projectMarchDir, "pi-sidecars");
+  return getLegacyPiSidecarDir(projectMarchDir);
 }
 
 export function getPiSidecarPath(projectMarchDir, sessionRef) {
-  return join(getPiSidecarDir(projectMarchDir), `${normalizeSessionRef(sessionRef)}.json`);
+  return getLegacyPiSidecarPath(projectMarchDir, sessionRef);
 }
 
 export function captureContextSidecar(engine, metadata = {}) {
-  return {
-    version: PI_SIDECAR_VERSION,
-    savedAt: new Date().toISOString(),
-    ...metadata,
-    cwd: engine.cwd,
-    modelId: engine.modelId,
-    provider: engine.provider,
-    sessionName: engine.sessionName ?? "",
-    thinkingLevel: engine.thinkingLevel,
-    namespace: engine.namespace,
-    pendingAssistantRecallHints: engine.pendingAssistantRecallHints ?? [],
-    turns: engine.turns,
-  };
+  return captureMarchSessionState(engine, {
+    sessionId: metadata.sessionId,
+    backend: {
+      type: "pi",
+      sessionId: metadata.sessionId ?? null,
+      sessionFile: metadata.sessionFile ?? null,
+      runtimeHost: Boolean(metadata.runtimeHost),
+    },
+    metadata,
+  });
 }
 
 export function savePiSessionSidecar({ projectMarchDir, sessionRef, engine, metadata = {} }) {
   return savePiSessionSidecarState({
     projectMarchDir,
     sessionRef,
-    state: captureContextSidecar(engine, metadata),
+    state: captureContextSidecar(engine, { sessionFile: sessionRef, ...metadata }),
   });
 }
 
 export function savePiSessionSidecarState({ projectMarchDir, sessionRef, state }) {
-  const sidecarDir = getPiSidecarDir(projectMarchDir);
-  mkdirSync(sidecarDir, { recursive: true });
-  validateSidecarState(state);
-  const path = getPiSidecarPath(projectMarchDir, sessionRef);
-  writeFileSync(path, JSON.stringify(state, null, 2), "utf8");
-  return { path, state };
+  return saveMarchSessionStateValue({
+    projectMarchDir,
+    sessionId: state.sessionId ?? state.backend?.sessionId ?? state.sessionFile ?? sessionRef,
+    state: normalizeLegacyState(state, sessionRef),
+  });
 }
 
 export function loadPiSessionSidecar({ projectMarchDir, sessionRef }) {
-  const path = getPiSidecarPath(projectMarchDir, sessionRef);
-  if (!existsSync(path)) return null;
-  const state = JSON.parse(readFileSync(path, "utf8"));
-  if (!isValidSidecarState(state)) {
-    throw new Error("Invalid pi session sidecar");
-  }
-  return { path, state };
+  return loadMarchSessionStateForPiBackend({ projectMarchDir, sessionId: null, sessionRef }) ?? loadLegacyPiSidecar({ projectMarchDir, sessionRef });
 }
 
-function validateSidecarState(state) {
-  if (!isValidSidecarState(state)) throw new Error("Invalid pi session sidecar");
+export function loadPiSessionContextState({ projectMarchDir, sessionRef, sessionId = null }) {
+  return loadMarchSessionStateForPiBackend({ projectMarchDir, sessionId, sessionRef });
 }
 
-function isValidSidecarState(state) {
-  return state?.version === PI_SIDECAR_VERSION && Boolean(state.cwd) && Array.isArray(state.turns);
-}
-
-function normalizeSessionRef(sessionRef) {
-  const ref = basename(String(sessionRef).trim()).replace(/\.jsonl$/i, "");
-  if (!ref || ref === "." || ref === "..") throw new Error("Invalid pi session reference");
-  return ref.replace(/[^a-zA-Z0-9._-]/g, "_");
+function normalizeLegacyState(state, sessionRef) {
+  return {
+    ...state,
+    sessionId: state.sessionId ?? state.backend?.sessionId ?? state.sessionFile ?? sessionRef,
+    backend: state.backend ?? {
+      type: "pi",
+      sessionId: state.sessionId ?? null,
+      sessionFile: state.sessionFile ?? sessionRef,
+      runtimeHost: Boolean(state.runtimeHost),
+    },
+  };
 }

package/src/session/state/march-session-state.mjs

@@ -0,0 +1,175 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { loadPiSessionTranscriptTurns } from "../transcript.mjs";
+
+export const MARCH_SESSION_STATE_VERSION = 1;
+
+export function getMarchSessionStateRoot(projectMarchDir) {
+  return join(projectMarchDir, "sessions");
+}
+
+export function getMarchSessionStateDir(projectMarchDir, sessionId) {
+  return join(getMarchSessionStateRoot(projectMarchDir), normalizeSessionId(sessionId));
+}
+
+export function getMarchSessionStatePath(projectMarchDir, sessionId) {
+  return join(getMarchSessionStateDir(projectMarchDir, sessionId), "state.json");
+}
+
+export function captureMarchSessionState(engine, { sessionId, backend = null, metadata = {} } = {}) {
+  return {
+    version: MARCH_SESSION_STATE_VERSION,
+    savedAt: new Date().toISOString(),
+    sessionId: sessionId ?? metadata.sessionId ?? backend?.sessionId ?? null,
+    backend,
+    ...metadata,
+    cwd: engine.cwd,
+    modelId: engine.modelId,
+    provider: engine.provider,
+    sessionName: engine.sessionName ?? "",
+    thinkingLevel: engine.thinkingLevel,
+    namespace: engine.namespace,
+    pendingAssistantRecallHints: engine.pendingAssistantRecallHints ?? [],
+    turns: engine.turns,
+  };
+}
+
+export function saveMarchSessionState({ projectMarchDir, sessionId, engine, backend = null, metadata = {} }) {
+  return saveMarchSessionStateValue({
+    projectMarchDir,
+    sessionId,
+    state: captureMarchSessionState(engine, { sessionId, backend, metadata }),
+  });
+}
+
+export function saveMarchSessionStateValue({ projectMarchDir, sessionId, state }) {
+  if (!sessionId) throw new Error("March session id is required");
+  const existing = loadMarchSessionState({ projectMarchDir, sessionId })?.state ?? null;
+  const nextState = normalizeMarchSessionStateForSave({ ...existing, ...state, renderTimeline: state.renderTimeline ?? existing?.renderTimeline });
+  validateMarchSessionState(nextState);
+  const dir = getMarchSessionStateDir(projectMarchDir, sessionId);
+  mkdirSync(dir, { recursive: true });
+  const path = getMarchSessionStatePath(projectMarchDir, sessionId);
+  writeFileSync(path, JSON.stringify({ ...nextState, sessionId: nextState.sessionId ?? sessionId }, null, 2), "utf8");
+  return { path, state: { ...nextState, sessionId: nextState.sessionId ?? sessionId } };
+}
+
+export function loadMarchSessionState({ projectMarchDir, sessionId }) {
+  const path = getMarchSessionStatePath(projectMarchDir, sessionId);
+  if (!existsSync(path)) return null;
+  const state = normalizeMarchSessionStateForSave(JSON.parse(readFileSync(path, "utf8")));
+  if (!isValidMarchSessionState(state)) throw new Error("Invalid March session state");
+  return { path, state };
+}
+
+export function loadMarchSessionContextState({ projectMarchDir, sessionId, backendSessionFile = null }) {
+  const stored = loadMarchSessionState({ projectMarchDir, sessionId });
+  if (!stored) return null;
+  const sessionFile = backendSessionFile ?? stored.state.backend?.sessionFile ?? stored.state.sessionFile ?? null;
+  return { ...stored, state: withBackendTranscriptTurns(stored.state, sessionFile) };
+}
+
+export function listMarchSessionStates({ projectMarchDir }) {
+  const root = getMarchSessionStateRoot(projectMarchDir);
+  if (!existsSync(root)) return [];
+  return readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => {
+      try {
+        return loadMarchSessionState({ projectMarchDir, sessionId: entry.name });
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+export function loadMarchSessionStateForPiBackend({ projectMarchDir, sessionId, sessionRef }) {
+  const marchState = sessionId ? loadMarchSessionContextState({ projectMarchDir, sessionId, backendSessionFile: sessionRef }) : null;
+  if (marchState) return marchState;
+  const matchingState = findMarchSessionStateByPiBackend({ projectMarchDir, sessionRef });
+  if (matchingState) return { ...matchingState, state: withBackendTranscriptTurns(matchingState.state, sessionRef) };
+  return loadLegacyPiSidecarContextState({ projectMarchDir, sessionRef });
+}
+
+function findMarchSessionStateByPiBackend({ projectMarchDir, sessionRef }) {
+  const normalizedRef = normalizeSessionRef(sessionRef);
+  return listMarchSessionStates({ projectMarchDir }).find(({ state }) => {
+    const sessionFile = state.backend?.sessionFile ?? state.sessionFile ?? null;
+    return sessionFile && normalizeSessionRef(sessionFile) === normalizedRef;
+  }) ?? null;
+}
+
+export function getLegacyPiSidecarDir(projectMarchDir) {
+  return join(projectMarchDir, "pi-sidecars");
+}
+
+export function getLegacyPiSidecarPath(projectMarchDir, sessionRef) {
+  return join(getLegacyPiSidecarDir(projectMarchDir), `${normalizeSessionRef(sessionRef)}.json`);
+}
+
+export function loadLegacyPiSidecar({ projectMarchDir, sessionRef }) {
+  const path = getLegacyPiSidecarPath(projectMarchDir, sessionRef);
+  if (!existsSync(path)) return null;
+  const state = normalizeMarchSessionStateForSave(JSON.parse(readFileSync(path, "utf8")));
+  if (!isValidMarchSessionState(state)) throw new Error("Invalid March session state");
+  return { path, state };
+}
+
+export function loadLegacyPiSidecarContextState({ projectMarchDir, sessionRef }) {
+  const legacy = loadLegacyPiSidecar({ projectMarchDir, sessionRef });
+  if (!legacy) return null;
+  return { ...legacy, state: withBackendTranscriptTurns(legacy.state, sessionRef) };
+}
+
+export function normalizeSessionId(sessionId) {
+  const value = String(sessionId ?? "").trim();
+  if (!value || value === "." || value === "..") throw new Error("Invalid March session id");
+  return value.replace(/[^a-zA-Z0-9._-]/g, "_");
+}
+
+function validateMarchSessionState(state) {
+  if (!isValidMarchSessionState(state)) throw new Error("Invalid March session state");
+}
+
+function isValidMarchSessionState(state) {
+  return state?.version === MARCH_SESSION_STATE_VERSION
+    && Boolean(state.cwd)
+    && Array.isArray(state.turns)
+    && Array.isArray(state.renderTimeline);
+}
+
+function normalizeMarchSessionStateForSave(state) {
+  return {
+    ...state,
+    renderTimeline: normalizePersistedRenderTimeline(state.renderTimeline),
+  };
+}
+
+function normalizePersistedRenderTimeline(events) {
+  if (!Array.isArray(events)) return [];
+  return events
+    .filter((event) => typeof event?.method === "string" && Array.isArray(event.args))
+    .map((event) => ({ method: event.method, args: event.args, at: event.at ?? null }));
+}
+
+function normalizeSessionRef(sessionRef) {
+  const ref = basename(String(sessionRef).trim()).replace(/\.jsonl$/i, "");
+  if (!ref || ref === "." || ref === "..") throw new Error("Invalid pi session reference");
+  return ref.replace(/[^a-zA-Z0-9._-]/g, "_");
+}
+
+function withBackendTranscriptTurns(state, sessionFile) {
+  if (!sessionFile) return { ...state };
+  let transcriptTurns = [];
+  try {
+    transcriptTurns = loadPiSessionTranscriptTurns(sessionFile);
+  } catch {
+    return { ...state };
+  }
+  if (transcriptTurns.length <= (state.turns?.length ?? 0)) return { ...state };
+  return {
+    ...state,
+    turns: transcriptTurns,
+  };
+}

package/src/session/state/march-session-sync.mjs

@@ -0,0 +1,20 @@
+import { saveMarchSessionState } from "./march-session-state.mjs";
+
+export function syncMarchSessionState({ enabled = false, projectMarchDir, engine, sessionStats, metadata = {} }) {
+  if (!enabled || !projectMarchDir || !sessionStats?.persisted || !sessionStats.sessionId) {
+    return null;
+  }
+
+  return saveMarchSessionState({
+    projectMarchDir,
+    sessionId: sessionStats.sessionId,
+    engine,
+    backend: {
+      type: "pi",
+      sessionId: sessionStats.sessionId,
+      sessionFile: sessionStats.sessionFile ?? null,
+      runtimeHost: Boolean(sessionStats.runtimeHost),
+    },
+    metadata,
+  });
+}

package/src/session/state/march-session-ui-state.mjs

@@ -0,0 +1,60 @@
+import { existsSync, readFileSync } from "node:fs";
+import { getMarchSessionStatePath, loadMarchSessionState, saveMarchSessionStateValue } from "./march-session-state.mjs";
+
+export function loadMarchSessionRenderTimeline({ projectMarchDir, sessionId }) {
+  const persistedRender = readPersistedRenderTimelineInfo({ projectMarchDir, sessionId });
+  const stored = loadMarchSessionState({ projectMarchDir, sessionId });
+  if (!stored) return null;
+  const renderTimeline = normalizeSessionRenderTimeline(stored.state.renderTimeline);
+  return {
+    path: stored.path,
+    renderTimeline: persistedRender.hasUiOwnedTimeline ? renderTimeline : renderTimelineFromTurns(stored.state.turns ?? []),
+  };
+}
+
+export function saveMarchSessionRenderTimeline({ projectMarchDir, sessionId, renderTimeline }) {
+  const stored = loadMarchSessionState({ projectMarchDir, sessionId });
+  if (!stored) return null;
+  return saveMarchSessionStateValue({
+    projectMarchDir,
+    sessionId,
+    state: {
+      ...stored.state,
+      renderTimeline: normalizeSessionRenderTimeline(renderTimeline),
+      renderTimelineUpdatedAt: new Date().toISOString(),
+    },
+  });
+}
+
+export function normalizeSessionRenderTimeline(events) {
+  if (!Array.isArray(events)) return [];
+  return events
+    .filter((event) => typeof event?.method === "string" && Array.isArray(event.args))
+    .map((event) => ({ method: event.method, args: event.args, at: event.at ?? null }));
+}
+
+function readPersistedRenderTimelineInfo({ projectMarchDir, sessionId }) {
+  try {
+    const path = getMarchSessionStatePath(projectMarchDir, sessionId);
+    if (!existsSync(path)) return { hasUiOwnedTimeline: false };
+    const raw = JSON.parse(readFileSync(path, "utf8"));
+    const rawTimeline = normalizeSessionRenderTimeline(raw.renderTimeline);
+    return { hasUiOwnedTimeline: Boolean(raw.renderTimelineUpdatedAt) || rawTimeline.length > 0 };
+  } catch {
+    return { hasUiOwnedTimeline: false };
+  }
+}
+
+function renderTimelineFromTurns(turns) {
+  return turns.flatMap((turn) => {
+    const events = [];
+    if (turn.userMessage) events.push({ method: "writeln", args: [turn.userMessage], at: null });
+    if (turn.assistantMessage) {
+      events.push({ method: "turnStart", args: [], at: null });
+      events.push({ method: "textDelta", args: [turn.assistantMessage], at: null });
+      events.push({ method: "assistantReplyEnd", args: [], at: null });
+      events.push({ method: "turnEnd", args: [], at: null });
+    }
+    return events;
+  });
+}