@nanhara/hara 0.122.7 → 0.123.0

package/dist/org-fleet/enroll.js

@@ -10,7 +10,7 @@
 //   GET  {gateway}/v1/roles       Bearer <device_token> -> {version, org_policy, roles:[…]}  (B3 digital-employee push-down)
 //   POST {gateway}/v1/chat/completions  (OpenAI-compatible; the normal agent traffic, Bearer <device_token>)
 import { homedir, hostname, platform } from "node:os";
-import { join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync, rmSync } from "node:fs";
 import { orgRolesDir } from "../org/roles.js";
 import { loadActiveProfile } from "../profile/profile.js";
@@ -117,6 +117,25 @@ export async function heartbeat(signal) {
         return false;
     }
 }
+const SAFE_ORG_ROLE_NAME = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+const WINDOWS_RESERVED_NAME = /^(?:CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])$/i;
+function isSafeBundleRole(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const role = value;
+    if (typeof role.name !== "string" || !SAFE_ORG_ROLE_NAME.test(role.name) || WINDOWS_RESERVED_NAME.test(role.name) ||
+        typeof role.system !== "string" || !role.system.trim())
+        return false;
+    for (const key of ["description", "model"]) {
+        if (role[key] !== undefined && typeof role[key] !== "string")
+            return false;
+    }
+    for (const key of ["owns", "rejects", "allow_tools", "deny_tools"]) {
+        if (role[key] !== undefined && (!Array.isArray(role[key]) || !role[key].every((item) => typeof item === "string")))
+            return false;
+    }
+    return true;
+}
 /** Render one bundle role into the markdown frontmatter the CLI role loader expects
  *  (src/org/roles.ts parseFrontmatter): name/description/owns/rejects/model/allowTools/denyTools, body=system. */
 function renderRoleMd(r) {
@@ -150,12 +169,19 @@ export async function syncOrgRoles(signal) {
         if (!res.ok)
             return 0;
         const bundle = (await res.json());
-        const roles = Array.isArray(bundle.roles) ? bundle.roles.filter((r) => r && r.name && r.system) : [];
+        const roles = Array.isArray(bundle.roles)
+            ? [...new Map(bundle.roles.filter(isSafeBundleRole).map((role) => [role.name, role])).values()]
+            : [];
         const dir = orgRolesDir();
         rmSync(dir, { recursive: true, force: true }); // authoritative replace
         mkdirSync(dir, { recursive: true });
-        for (const r of roles)
-            writeFileSync(join(dir, `${r.name}.md`), renderRoleMd(r), "utf8");
+        const root = resolve(dir);
+        for (const r of roles) {
+            const target = resolve(root, `${r.name}.md`);
+            if (dirname(target) !== root)
+                continue;
+            writeFileSync(target, renderRoleMd(r), "utf8");
+        }
         // org policy sidecar (model/tool/approval floors the CLI enforces; skipped by the .md-only role loader)
         writeFileSync(join(dir, "_policy.json"), JSON.stringify({ version: bundle.version ?? 0, org_policy: bundle.org_policy ?? {} }, null, 2) + "\n", "utf8");
         return roles.length;

package/dist/security/guardian.js

@@ -16,7 +16,7 @@
 // Plus a deterministic circuit-breaker: N guardian BLOCKS in one run (or an escalating-destructive runaway)
 // trips a hard stop that requires explicit user confirmation to continue — a harder stop than the soft
 // stuck-guard nudge, and one that aborts safely (never hangs) when there's no interactive user.
-import { resolve, isAbsolute } from "node:path";
+import { resolve, isAbsolute, relative, sep, win32 } from "node:path";
 import { boundedProviderTurn } from "../providers/bounded-turn.js";
 import { canonicalize, splitCompound } from "./permissions.js";
 // ── Deterministic risk classifier ────────────────────────────────────────────────────────────────────
@@ -93,10 +93,18 @@ function redirectionTargets(canonical) {
 export function isOutsideRoot(p, cwd) {
     if (!p || p === "/dev/null" || p === "-")
         return false;
-    const expanded = p.replace(/^~(?=\/|$)/, process.env.HOME ?? "~");
-    const abs = isAbsolute(expanded) ? resolve(expanded) : resolve(cwd, expanded);
-    const root = resolve(cwd);
-    return abs !== root && !abs.startsWith(root + "/");
+    // Windows uses `\\` boundaries, so concatenating `root + "/"` classifies every ordinary child as
+    // outside. `relative` expresses containment portably. Detect an explicit Windows root as well so the
+    // classifier remains testable and safe when a control-plane caller runs on another host.
+    const windowsRoot = win32.isAbsolute(cwd);
+    const pathApi = windowsRoot
+        ? { resolve: win32.resolve, isAbsolute: win32.isAbsolute, relative: win32.relative, sep: win32.sep }
+        : { resolve, isAbsolute, relative, sep };
+    const expanded = p.replace(/^~(?=[/\\]|$)/, process.env.HOME ?? process.env.USERPROFILE ?? "~");
+    const abs = pathApi.isAbsolute(expanded) ? pathApi.resolve(expanded) : pathApi.resolve(cwd, expanded);
+    const root = pathApi.resolve(cwd);
+    const rel = pathApi.relative(root, abs);
+    return rel !== "" && (rel === ".." || rel.startsWith(`..${pathApi.sep}`) || pathApi.isAbsolute(rel));
 }
 /** Collect the file paths an edit-kind tool would write/delete, from its tool input. */
 export function editPaths(name, input) {

package/dist/security/private-state.js

@@ -248,7 +248,9 @@ function tightenTree(root, budget) {
             for (const entry of entries)
                 stack.push(join(path, entry));
         }
-        else if (info.isFile()) {
+        else if (info.isFile() && info.nlink === 1) {
+            // chmod follows hard links at the inode level. An attacker-controlled alias must not let startup
+            // tighten (and thereby mutate) an unrelated file outside ~/.hara; dedicated readers reject it later.
             chmodPrivate(path, 0o600);
         }
     }

package/dist/serve/protocol.js

@@ -8,7 +8,8 @@
 //   session.list      {cwd?}                     → {sessions:[{id,title,cwd,model,updatedAt}]}
 //   session.create    {cwd?,approval?}           → {sessionId,model}
 //   session.resume    {sessionId}                → {sessionId,model,history:[{role,text}]}
-//   session.send      {sessionId,text,images?}   → (streams events, then) {reply,usage}
+//   session.send      {sessionId,text,images?,newTask?} → (streams events, then) {reply,usage,taskId,turnId}
+//   session.steer     {sessionId,text,expectedTurnId} → {accepted,taskId,turnId}
 //                      images: [{path,mediaType?}] — pasted screenshots etc., inlined for vision models
 //   session.interrupt {sessionId}                → {}
 //   approval.reply    {approvalId,allow,always?}  → {}

package/dist/serve/server.js

@@ -28,10 +28,11 @@ import { parseSchedule, describeSchedule } from "../cron/schedule.js";
 import { loadTasks } from "../tools/task.js";
 import { listPending, resolvePending } from "../gateway/flows-pending.js";
 import { disposeTodoScope, restoreTodos, serializeTodos } from "../tools/todo.js";
-import { disposeReminderScope } from "../agent/reminders.js";
+import { INTERJECT_PREFIX, disposeReminderScope } from "../agent/reminders.js";
 import { SessionHub, realStore } from "./sessions.js";
 import { parseFrame, rpcResult, rpcError, rpcNotify, ERR, PROTOCOL_VERSION } from "./protocol.js";
 import { readModelContextFileSync } from "../fs-read.js";
+import { createTaskExecution, continueTaskExecution, finishTaskExecution, newSteerInteraction, newTurnInteraction, recordTaskSteering, taskExecutionContext, } from "../session/task.js";
 const APPROVAL_TIMEOUT_MS = 300_000; // an unanswered approval denies after 5 min (never hangs a turn)
 const COMPACT_TIMEOUT_MS = 60_000;
 const SHUTDOWN_GRACE_MS = 2_000;
@@ -301,11 +302,31 @@ export async function startServe(opts, deps) {
         }
     }
     /** Run one turn on a session, streaming events to all authed clients. */
-    const runTurn = async (s, text, images) => {
+    const runTurn = async (s, text, images, forceNewTask = false) => {
         const sessionId = s.meta.id;
         s.busy = true;
         const turnAbort = new AbortController();
         s.abort = turnAbort;
+        s.pendingInput = [];
+        const interaction = !forceNewTask && s.resumeTaskPending && s.task
+            ? newSteerInteraction(s.task.turnId)
+            : newTurnInteraction();
+        if (interaction.kind === "steer") {
+            const continued = continueTaskExecution(s.task, interaction);
+            if (!continued.ok) {
+                s.abort = null;
+                s.busy = false;
+                throw new Error(continued.reason);
+            }
+            s.task = continued.task;
+        }
+        else {
+            s.task = createTaskExecution(text, interaction.turnId);
+        }
+        s.resumeTaskPending = false;
+        const executionContext = taskExecutionContext(s.task, interaction);
+        hub.save(s); // crash-safe running identity before provider/tool side effects
+        broadcast("event.turn_start", { sessionId, taskId: s.task.id, turnId: s.task.turnId });
         const historyStart = s.history.length;
         const before = { input: s.stats.input, output: s.stats.output };
         const sink = {
@@ -361,49 +382,63 @@ export async function startServe(opts, deps) {
             // @file mentions expand to file contents, same as the CLI (`@src/foo.ts` in the composer works).
             // Pasted images ride along as NeutralMsg.images — a vision-capable model sees them inline.
             s.history.push({ role: "user", content: await expandMentionsAsync(content, s.meta.cwd, { signal: turnAbort.signal }), ...(images && images.length ? { images } : {}) });
-            const outcome = await runAgent(s.history, {
-                provider: s.provider,
-                ctx: {
-                    cwd: s.meta.cwd,
-                    sandbox: deps.sandbox,
-                    todoScope: sessionId,
-                    spawn: (t, role, signal) => deps.spawnSubagent(s.provider, s.meta.cwd, s.projectContext, s.stats, t, role, signal),
-                    ui: sink,
-                },
-                approval: s.approval,
-                confirm,
-                autoApprove: s.autoApprove,
-                projectContext: s.projectContext,
-                memory: memoryDigest(s.meta.cwd),
-                continuationSession: s.continuationSession,
-                stats: s.stats,
-                signal: turnAbort.signal,
-                onProviderTurn: (turn) => {
-                    s.pendingProviderTurns += 1;
-                    const settled = () => {
-                        s.pendingProviderTurns = Math.max(0, s.pendingProviderTurns - 1);
-                        if (closing)
-                            hub.releaseIdle();
-                    };
-                    void turn.then(settled, settled);
-                },
-                onToolRun: (toolRun) => {
-                    s.pendingToolRuns += 1;
-                    const settled = () => {
-                        s.pendingToolRuns = Math.max(0, s.pendingToolRuns - 1);
-                        // `abort === null` means the logical turn already returned. Keep the session busy/locked until
-                        // every late side-effect-capable Promise has physically stopped.
-                        if (s.pendingToolRuns === 0 && s.abort === null)
-                            s.busy = false;
-                        if (closing)
-                            hub.releaseIdle();
-                    };
-                    void toolRun.then(settled, settled);
-                },
-                guardian: turnGuardian,
-                ...(deps.runLimits?.(s.meta.cwd) ?? {}),
-            });
+            let outcome;
+            do {
+                outcome = await runAgent(s.history, {
+                    provider: s.provider,
+                    ctx: {
+                        cwd: s.meta.cwd,
+                        sandbox: deps.sandbox,
+                        todoScope: sessionId,
+                        spawn: (t, role, signal) => deps.spawnSubagent(s.provider, s.meta.cwd, s.projectContext, s.stats, t, role, signal),
+                        ui: sink,
+                    },
+                    approval: s.approval,
+                    confirm,
+                    autoApprove: s.autoApprove,
+                    projectContext: s.projectContext,
+                    memory: memoryDigest(s.meta.cwd),
+                    continuationSession: s.continuationSession,
+                    executionContext,
+                    pendingInput: async () => s.pendingInput.splice(0),
+                    stats: s.stats,
+                    signal: turnAbort.signal,
+                    onProviderTurn: (turn) => {
+                        s.pendingProviderTurns += 1;
+                        const settled = () => {
+                            s.pendingProviderTurns = Math.max(0, s.pendingProviderTurns - 1);
+                            if (closing)
+                                hub.releaseIdle();
+                        };
+                        void turn.then(settled, settled);
+                    },
+                    onToolRun: (toolRun) => {
+                        s.pendingToolRuns += 1;
+                        const settled = () => {
+                            s.pendingToolRuns = Math.max(0, s.pendingToolRuns - 1);
+                            // `abort === null` means the logical turn already returned. Keep the session busy/locked until
+                            // every late side-effect-capable Promise has physically stopped.
+                            if (s.pendingToolRuns === 0 && s.abort === null)
+                                s.busy = false;
+                            if (closing)
+                                hub.releaseIdle();
+                        };
+                        void toolRun.then(settled, settled);
+                    },
+                    guardian: turnGuardian,
+                    ...(deps.runLimits?.(s.meta.cwd) ?? {}),
+                });
+                // A steer may land after the agent's final in-loop drain but before the logical turn returns. Keep
+                // it in the same task/run instead of making the client retry it as an unrelated session.send.
+                const trailing = s.pendingInput.splice(0);
+                if (!trailing.length || turnAbort.signal.aborted || outcome.status !== "completed")
+                    break;
+                s.history.push(...trailing);
+                hub.save(s);
+            } while (true);
             s.meta.todos = serializeTodos(sessionId);
+            s.task = finishTaskExecution(s.task, outcome, s.meta.todos, turnAbort.signal.aborted);
+            s.resumeTaskPending = Boolean(s.task && s.task.status !== "completed");
             hub.save(s);
             const usage = { input: s.stats.input - before.input, output: s.stats.output - before.output };
             // context watermark rides along with every turn end (codex thread/tokenUsage/updated pattern) —
@@ -415,14 +450,22 @@ export async function startServe(opts, deps) {
                     : outcome.status === "halted"
                         ? "agent turn halted by a safety control"
                         : "agent turn failed");
-                broadcast("event.turn_end", { sessionId, reply: "", error: failure, status: outcome.status, usage, ctx });
+                broadcast("event.turn_end", { sessionId, taskId: s.task.id, turnId: s.task.turnId, reply: "", error: failure, status: outcome.status, usage, ctx });
                 throw new Error(failure);
             }
             // A persistent session may already contain many assistant messages. Only messages appended by THIS
             // request are eligible for its reply; a failed/empty turn must never replay a previous success.
             const reply = lastAssistantText(s.history.slice(historyStart));
-            broadcast("event.turn_end", { sessionId, reply, usage, ctx });
-            return { reply, usage, ctx };
+            broadcast("event.turn_end", { sessionId, taskId: s.task.id, turnId: s.task.turnId, reply, usage, ctx });
+            return { reply, usage, ctx, taskId: s.task.id, turnId: s.task.turnId };
+        }
+        catch (error) {
+            if (s.task?.status === "running") {
+                s.task = finishTaskExecution(s.task, { status: "error", error: error instanceof Error ? error.message : String(error) }, s.meta.todos ?? [], turnAbort.signal.aborted);
+                s.resumeTaskPending = Boolean(s.task && s.task.status !== "completed");
+                hub.save(s);
+            }
+            throw error;
         }
         finally {
             s.abort = null;
@@ -536,7 +579,7 @@ export async function startServe(opts, deps) {
                         // clients feature-detect up front instead of probing for -32601 per call. `p.capabilities`
                         // (client-declared) is accepted and currently unused — reserved for opt-outs/experimental gating.
                         const methods = [
-                            "session.list", "session.create", "session.resume", "session.send", "session.interrupt", "session.set-model",
+                            "session.list", "session.create", "session.resume", "session.send", "session.steer", "session.interrupt", "session.set-model",
                             "session.rename", "session.archive", "session.compact", "session.rewind", "session.context", "session.delete", "session.fork",
                             "approval.reply", "plugins.list", "plugins.set", "skills.list", "models.list", "files.search", "project.panels",
                             "automation.list", "automation.add", "automation.toggle", "automation.delete",
@@ -595,7 +638,18 @@ export async function startServe(opts, deps) {
                                 return reply(rpcError(id, ERR.INTERNAL, `provider not authenticated for pinned model '${r.session.meta.model}'`));
                             }
                             r.session.projectContext = loadAgentContext(r.session.meta.cwd) || undefined;
-                            return reply(rpcResult(id, { sessionId: r.session.meta.id, model: r.session.meta.model, history: historyForClient(r.session.history) }));
+                            return reply(rpcResult(id, {
+                                sessionId: r.session.meta.id,
+                                model: r.session.meta.model,
+                                history: historyForClient(r.session.history),
+                                task: r.session.task ? {
+                                    id: r.session.task.id,
+                                    objective: r.session.task.objective,
+                                    status: r.session.task.status,
+                                    turnId: r.session.task.turnId,
+                                    updatedAt: r.session.task.updatedAt,
+                                } : undefined,
+                            }));
                         }
                         case "session.send": {
                             if (typeof p.sessionId !== "string" || typeof p.text !== "string" || !p.text)
@@ -608,9 +662,27 @@ export async function startServe(opts, deps) {
                             const images = Array.isArray(p.images)
                                 ? p.images.filter((im) => im && typeof im.path === "string").map((im) => ({ path: im.path, mediaType: typeof im.mediaType === "string" ? im.mediaType : "image/png" }))
                                 : undefined;
-                            const r = await runTurn(s, p.text, images);
+                            const r = await runTurn(s, p.text, images, p.newTask === true);
                             return reply(rpcResult(id, r));
                         }
+                        case "session.steer": {
+                            if (typeof p.sessionId !== "string" || typeof p.text !== "string" || !p.text || typeof p.expectedTurnId !== "string") {
+                                return reply(rpcError(id, ERR.PARAMS, "sessionId + text + expectedTurnId required"));
+                            }
+                            const s = hub.get(p.sessionId);
+                            if (!s)
+                                return reply(rpcError(id, ERR.NO_SESSION, "no such live session"));
+                            if (!s.busy || !s.abort || s.configuring)
+                                return reply(rpcError(id, ERR.BUSY, "there is no steerable running turn"));
+                            const expanded = await expandMentionsAsync(p.text, s.meta.cwd, { signal: s.abort.signal });
+                            const recorded = recordTaskSteering(s.task, p.expectedTurnId, expanded);
+                            if (!recorded.ok)
+                                return reply(rpcError(id, ERR.BUSY, recorded.reason));
+                            s.task = recorded.task;
+                            s.pendingInput.push({ role: "user", content: `${INTERJECT_PREFIX}\n\n${expanded}` });
+                            hub.save(s); // task audit is durable even before the running loop reaches its next drain
+                            return reply(rpcResult(id, { accepted: true, taskId: s.task.id, turnId: s.task.turnId }));
+                        }
                         case "session.interrupt": {
                             const s = typeof p.sessionId === "string" ? hub.get(p.sessionId) : undefined;
                             if (!s)
@@ -896,6 +968,9 @@ export async function startServe(opts, deps) {
                                 return reply(rpcError(id, ERR.PARAMS, `n out of range (1..${s.history.filter((m) => m.role === "user").length})`));
                             s.history.length = 0;
                             s.history.push(...next);
+                            s.task = undefined;
+                            s.resumeTaskPending = false;
+                            s.pendingInput = [];
                             hub.save(s);
                             return reply(rpcResult(id, { sessionId: s.meta.id, history: historyForClient(s.history) }));
                         }

package/dist/serve/sessions.js

@@ -1,4 +1,5 @@
 import { newSessionId, saveSession, loadSession, listSessions, acquireSessionLock, releaseSessionLock, deleteSession, deriveTitle, } from "../session/store.js";
+import { forkTaskExecution, recoverTaskExecution } from "../session/task.js";
 /** The real ~/.hara/sessions store (default). */
 export const realStore = {
     load: loadSession,
@@ -26,7 +27,7 @@ export class SessionHub {
             if (!current)
                 return false;
             mutate(current);
-            this.store.save(current.meta, current.history);
+            this.store.save(current.meta, current.history, current.task);
             return true;
         }
         finally {
@@ -47,7 +48,7 @@ export class SessionHub {
         const lock = this.store.acquire(meta.id); // fresh UUID, but filesystem errors must still fail closed
         if (!lock.ok)
             throw new Error(`could not acquire session lock for ${meta.id}${lock.pid ? ` (held by pid ${lock.pid})` : ""}`);
-        const s = { meta, history: [], provider: o.provider, approval: o.approval, autoApprove: new Set(), stats: { input: 0, output: 0 }, projectContext: o.projectContext, continuationSession: false, busy: false, configuring: false, pendingProviderTurns: 0, pendingToolRuns: 0, abort: null };
+        const s = { meta, history: [], resumeTaskPending: false, pendingInput: [], provider: o.provider, approval: o.approval, autoApprove: new Set(), stats: { input: 0, output: 0 }, projectContext: o.projectContext, continuationSession: false, busy: false, configuring: false, pendingProviderTurns: 0, pendingToolRuns: 0, abort: null };
         try {
             this.sessions.set(meta.id, s);
             this.store.save(meta, []); // an empty newly-created thread must survive restart and appear in lists
@@ -76,7 +77,8 @@ export class SessionHub {
                 return { missing: true };
             // Credential/provider routing is live, while the model remains the session's explicit pin.
             prior.meta.provider = o.provider.id;
-            const s = { meta: prior.meta, history: [...prior.history], provider: o.provider, approval: o.approval, autoApprove: new Set(), stats: { input: 0, output: 0 }, projectContext: o.projectContext, continuationSession: prior.history.length > 0, busy: false, configuring: false, pendingProviderTurns: 0, pendingToolRuns: 0, abort: null, effort: prior.meta.effort };
+            const task = recoverTaskExecution(prior.task);
+            const s = { meta: prior.meta, history: [...prior.history], task, resumeTaskPending: Boolean(task && task.status !== "completed"), pendingInput: [], provider: o.provider, approval: o.approval, autoApprove: new Set(), stats: { input: 0, output: 0 }, projectContext: o.projectContext, continuationSession: prior.history.length > 0, busy: false, configuring: false, pendingProviderTurns: 0, pendingToolRuns: 0, abort: null, effort: prior.meta.effort };
             this.sessions.set(id, s);
             keepLock = true; // live session owns it until delete/releaseAll
             return { session: s };
@@ -114,7 +116,7 @@ export class SessionHub {
             if (first && "content" in first && typeof first.content === "string")
                 s.meta.title = deriveTitle(first.content);
         }
-        this.store.save(s.meta, s.history);
+        this.store.save(s.meta, s.history, s.task);
     }
     /** Rename a session (live or on-disk). Returns false when the id is unknown. */
     rename(id, title) {
@@ -123,7 +125,7 @@ export class SessionHub {
             if (live.busy || live.configuring)
                 return false;
             live.meta.title = title;
-            this.store.save(live.meta, live.history);
+            this.store.save(live.meta, live.history, live.task);
             return true;
         }
         return this.mutateStored(id, (current) => {
@@ -137,7 +139,7 @@ export class SessionHub {
             if (live.busy || live.configuring)
                 return false;
             live.meta.archived = on;
-            this.store.save(live.meta, live.history);
+            this.store.save(live.meta, live.history, live.task);
             return true;
         }
         return this.mutateStored(id, (current) => {
@@ -172,6 +174,9 @@ export class SessionHub {
         const s = {
             meta,
             history: [...src.history],
+            task: forkTaskExecution(src.task),
+            resumeTaskPending: Boolean(src.task),
+            pendingInput: [],
             provider: o.provider,
             approval: o.approval,
             autoApprove: new Set(),
@@ -187,7 +192,7 @@ export class SessionHub {
         };
         try {
             this.sessions.set(meta.id, s);
-            this.store.save(meta, s.history); // persist immediately — a fork should survive a crash unsent
+            this.store.save(meta, s.history, s.task); // persist immediately — a fork should survive a crash unsent
             return { session: s };
         }
         catch (error) {

package/dist/session/store.js

@@ -4,6 +4,7 @@ import { join } from "node:path";
 import { chmodSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { redactSensitiveValue } from "../security/secrets.js";
+import { isTaskExecution } from "./task.js";
 /** Derive the session source from the spawn environment — the gateway subprocess runs with
  *  HARA_GATEWAY=<platform>, the cron runner with HARA_CRON=1 (+ HARA_CRON_NAME=<job name>). */
 export function sessionSourceFromEnv() {
@@ -345,12 +346,39 @@ function redactedSessionCopy(data) {
         safe.meta.archived = data.meta.archived;
     if (data.meta.gatewayOwner !== undefined)
         safe.meta.gatewayOwner = data.meta.gatewayOwner;
+    if (data.task && safe.task) {
+        // Task objective/steering are free-form and stay redacted. Execution identity and transition metadata
+        // are structural: preserve them exactly so resume/expectedTurnId validation cannot be corrupted by a
+        // credential-looking identifier.
+        safe.task.schemaVersion = data.task.schemaVersion;
+        safe.task.id = data.task.id;
+        safe.task.status = data.task.status;
+        safe.task.turnId = data.task.turnId;
+        safe.task.createdAt = data.task.createdAt;
+        safe.task.updatedAt = data.task.updatedAt;
+        safe.task.startedAt = data.task.startedAt;
+        if (data.task.endedAt !== undefined)
+            safe.task.endedAt = data.task.endedAt;
+        if (data.task.lastOutcome !== undefined)
+            safe.task.lastOutcome = data.task.lastOutcome;
+        if (data.task.steering && safe.task.steering) {
+            for (let index = 0; index < data.task.steering.length; index++) {
+                const source = data.task.steering[index];
+                const target = safe.task.steering[index];
+                if (!source || !target)
+                    continue;
+                target.id = source.id;
+                target.turnId = source.turnId;
+                target.createdAt = source.createdAt;
+            }
+        }
+    }
     return safe;
 }
-export function saveSession(meta, history) {
+export function saveSession(meta, history, task) {
     checkedSessionId(meta.id);
     meta.updatedAt = new Date().toISOString();
-    const safe = redactedSessionCopy({ meta, history });
+    const safe = redactedSessionCopy({ meta, history, ...(task ? { task } : {}) });
     const target = sessionFile(meta.id);
     const tmp = `${target}.${process.pid}.${randomUUID()}.tmp`;
     let fd;
@@ -452,7 +480,8 @@ function isSessionMeta(value) {
 function isSessionData(d) {
     const o = d;
     return !!o && typeof o === "object" && !Array.isArray(o) && isSessionMeta(o.meta) &&
-        Array.isArray(o.history) && o.history.every(isNeutralMessage);
+        Array.isArray(o.history) && o.history.every(isNeutralMessage) &&
+        (o.task === undefined || isTaskExecution(o.task));
 }
 /** Read only. Legacy plaintext is redacted in the returned in-memory copy but intentionally not migrated
  *  here: listing/resuming must not perform an unlocked write. The next explicit save atomically migrates it. */