fuli-context 0.8.0 → 0.8.1

package/src/agents/claude-code/lifecycle-hook.js

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+import { withTranscriptGuard } from '../../conversations/transcript-guard.js';
+import { compactTaskContext } from '../../conversations/task-context-view.js';
+import { syncConversationTranscript, withTranscriptNotice, claimTranscriptBoundary, recordTranscriptTaskEntry } from '../../conversations/sync-transcript.js';
+import { normalizeClaudeRecord, verifyClaudeTranscript } from './conversation-transcript.js';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { callAgentTool } from '../../agent-tools.js';
+import { createRuntimeLeaseClient } from '../../adaptive-runtime/lease-client.js';
+import { openFederatedGraphApplication } from '../../graphiti/federated-application.js';
+import { resolveGraphRuntimeOptions } from '../../graphiti/runtime-config.js';
+import { hookAdditionalContextToolResult } from '../../mcp/tool-result.js';
+import { boundedHookMessage } from '../lifecycle-message.js';
+
+export async function claudeLifecycleOutput(event, input, invoke) {
+  if (!['UserPromptSubmit', 'Stop'].includes(event)) throw new TypeError('Unsupported Claude lifecycle event');
+  const sessionId = input?.session_id;
+  if (typeof sessionId !== 'string' || !sessionId.trim() || sessionId.length > 256) {
+    throw new TypeError('Claude lifecycle requires a host session identifier');
+  }
+  const source = { sourceApplication: 'claude_code', sourceSessionId: sessionId };
+  if (event === 'UserPromptSubmit') {
+    if (typeof input.cwd !== 'string' || !input.cwd.trim() || typeof input.prompt !== 'string') {
+      throw new TypeError('Claude task entry requires cwd and prompt');
+    }
+    const context = await invoke('begin_task_context', {
+      sessionId, projectPath: input.cwd, taskPrompt: input.prompt.slice(0, 8192), ...source
+    });
+    return JSON.parse(hookAdditionalContextToolResult(compactTaskContext(context), {
+      hookEventName: event,
+      label: 'Fuli task context. Apply effective_preferences and use taskContextToken for the final checkpoint.',
+      limitBytes: 128 * 1024,
+      itemLimit: 1000
+    }).content[0].text);
+  }
+  const check = await invoke('verify_task_checkpoint', { sessionId, ...source });
+  const reason = boundedHookMessage(check?.reason);
+  if (check?.decision !== 'block' || !reason.trim()) return {};
+  if (input.stop_hook_active === true) {
+    if (typeof check.task_context_token === 'string' && check.task_context_token.trim()) {
+      await invoke('checkpoint_task_knowledge', {
+        taskContextToken: check.task_context_token,
+        disposition: 'retain_nothing',
+        reason: 'Claude Code Stop hook fallback after one checkpoint continuation.',
+        workLog: { status: 'incomplete', summary: 'The host stopped before the employee submitted a work summary. Review the prior task before resuming.' },
+        ...source
+      });
+    }
+    return {};
+  }
+  return { decision: 'block', reason };
+}
+
+export function claudeLifecycleUnavailable(event) {
+  const warning = 'Fuli context is unavailable; memory recovery and task checkpoint are not verified. '
+    + 'Continue with the user request and use Fuli MCP when it becomes available.';
+  return event === 'UserPromptSubmit'
+    ? { systemMessage: warning, hookSpecificOutput: { hookEventName: event, additionalContext: warning } }
+    : { systemMessage: warning };
+}
+
+export async function runClaudeLifecycleHook(args, dependencies = {}) {
+  const event = args[args.indexOf('--event') + 1];
+  const input = await (dependencies.readInput ?? readHookInput)();
+  if (dependencies.invoke) return claudeLifecycleOutput(event, input, dependencies.invoke);
+  const { runtimeConfigPath } = (dependencies.resolveRuntimeOptions ?? resolveGraphRuntimeOptions)(
+    args, dependencies.env ?? process.env
+  );
+  let app;
+  let leases;
+  try {
+    app = (dependencies.openApplication ?? openFederatedGraphApplication)({ runtimeConfigPath });
+    leases = (dependencies.createLeases ?? createRuntimeLeaseClient)({ runtimeConfigPath });
+    const request = { signal: dependencies.signal };
+    return await leases.withGraphLease('claude-code-lifecycle', async () => {
+      try {
+        if (app.getCapturePolicy?.().enabled && input.transcript_path) dependencies.onTranscriptGuard?.();
+        return await withTranscriptGuard(runtimeConfigPath, input, 'claude_code', app.getCapturePolicy?.().enabled, async guard => {
+          let sync = await syncConversationTranscript(app, input, 'claude_code', {
+            normalize: normalizeClaudeRecord, verify: verifyClaudeTranscript
+          }, guard);
+          if (event === 'UserPromptSubmit' && sync.entryBlocked) return { decision: 'block', reason: sync.reason };
+          const entryGuard = sync.status === 'capture_disabled' ? null : guard;
+          if (event === 'UserPromptSubmit' && entryGuard?.value) await entryGuard.write({ ...entryGuard.value, phase: 'beginning' });
+          const output = await claudeLifecycleOutput(event, input, async (name, parameters) => {
+            const context = await (dependencies.callTool ?? callAgentTool)(app, name, parameters, request);
+            if (name === 'begin_task_context') await recordTranscriptTaskEntry(entryGuard, context);
+            return context;
+          });
+          if (event === 'UserPromptSubmit') sync = await claimTranscriptBoundary(app, input, 'claude_code', sync, {
+            normalize: normalizeClaudeRecord, verify: verifyClaudeTranscript
+          }, entryGuard);
+          if (event === 'UserPromptSubmit' && sync.entryBlocked) return { decision: 'block', reason: sync.reason };
+          return withTranscriptNotice(output, sync);
+        });
+      } catch (error) {
+        if (event !== 'UserPromptSubmit' || !app.getCapturePolicy?.().enabled || !input.transcript_path) throw error;
+        return { decision: 'block', reason: error.code === 'EADDRINUSE'
+          ? 'The session handoff lock is occupied. Retry after the current hook finishes; if it persists, start a new host session and resume the intended Agent.'
+          : 'Fuli transcript handoff could not be completed safely. Retry task entry; no previous Agent context was supplied.' };
+      }
+    }, request);
+  } finally {
+    await Promise.allSettled([close(leases), close(app)]);
+  }
+}
+
+async function close(resource) { await resource?.close(); }
+
+async function readHookInput() {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of process.stdin) {
+    size += chunk.length;
+    if (size > 256 * 1024) throw new TypeError('Hook input exceeds limit');
+    chunks.push(chunk);
+  }
+  return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const event = args[args.indexOf('--event') + 1];
+  const configured = args.includes('--timeout-ms') ? Number(args[args.indexOf('--timeout-ms') + 1]) : 28000;
+  const timeoutMs = Number.isSafeInteger(configured) && configured > 0 && configured <= 2_147_483_647
+    ? configured : 28000;
+  const controller = new AbortController();
+  let emitted = false;
+  let guarded = false;
+  const emit = (output, callback) => {
+    if (emitted) return;
+    emitted = true;
+    process.stdout.write(`${JSON.stringify(output)}\n`, callback);
+  };
+  // Finish before the host timeout, even if a dependency ignores cancellation.
+  // No prompt, transcript, path or raw exception is written to diagnostics.
+  const deadline = setTimeout(() => {
+    controller.abort();
+    emit(guarded && event === 'UserPromptSubmit' ? { decision: 'block', reason: 'Fuli transcript handoff timed out. Retry task entry; the previous Agent context was not supplied.' } : claudeLifecycleUnavailable(event), () => process.exit(0));
+  }, timeoutMs);
+  const abort = setTimeout(() => controller.abort(), Math.max(1, timeoutMs - 1500));
+  try {
+    const output = await runClaudeLifecycleHook(args, { signal: controller.signal, onTranscriptGuard: () => { guarded = true; } });
+    emit(output);
+  } catch {
+    emit(claudeLifecycleUnavailable(event));
+  } finally {
+    clearTimeout(abort);
+    clearTimeout(deadline);
+  }
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) await main();

package/src/agents/claude-code/lifecycle-hooks.js

@@ -0,0 +1,20 @@
+import { dirname, join } from 'node:path';
+import { quoteShellArgument } from '../../cli/shell-argument.js';
+
+export const CLAUDE_LIFECYCLE_MARKER = '--fuli-claude-lifecycle';
+
+export function claudeLifecycleCommand(context, event, timeoutSec) {
+  const script = context.claudeLifecycleHookPath ??
+    join(dirname(context.mcpServerPath), 'agents', 'claude-code', 'lifecycle-hook.js');
+  return [
+    context.nodePath, script, CLAUDE_LIFECYCLE_MARKER,
+    '--runtime-config', context.runtimeConfigPath, '--event', event,
+    '--timeout-ms', String(Math.max(100, timeoutSec * 1000 - 2000))
+  ].map(value => quoteShellArgument(value, context.platform)).join(' ');
+}
+
+export function isClaudeLifecycleCommand(hook) {
+  return hook?.type === 'command' && typeof hook.command === 'string' &&
+    hook.command.includes(CLAUDE_LIFECYCLE_MARKER) &&
+    hook.command.includes('lifecycle-hook.js');
+}

package/src/agents/codex/conversation-transcript.js

@@ -0,0 +1,22 @@
+// Codex rollout v1: visible response items only; event_msg mirrors are omitted.
+export function normalizeCodexRecord(record) {
+  if (record?.type !== 'response_item') return [];
+  const item = record.payload;
+  if (item?.type === 'message' && ['user', 'assistant'].includes(item.role)) {
+    const content = (item.content ?? []).filter(block => ['input_text', 'output_text'].includes(block.type))
+      .map(block => block.text ?? '').join('\n');
+    return content ? [{ role: item.role, kind: 'message', content }] : [];
+  }
+  if (['function_call', 'custom_tool_call'].includes(item?.type)) {
+    return [{ role: 'assistant', kind: 'tool_call', content: JSON.stringify({
+      call_id: item.call_id, name: item.name, arguments: item.arguments ?? item.input
+    }) }];
+  }
+  if (['function_call_output', 'custom_tool_call_output'].includes(item?.type)) {
+    return [{ role: 'tool', kind: 'tool_result', content: JSON.stringify({ call_id: item.call_id, output: item.output }) }];
+  }
+  return [];
+}
+export function verifyCodexTranscript(firstRecord, sessionId) {
+  return firstRecord?.type === 'session_meta' && firstRecord.payload?.id === sessionId;
+}

package/src/agents/codex/lifecycle-hook.js

@@ -1,4 +1,9 @@
 #!/usr/bin/env node
+import { withTranscriptGuard } from '../../conversations/transcript-guard.js';
+import { compactTaskContext } from '../../conversations/task-context-view.js';
+import { syncConversationTranscript, withTranscriptNotice, claimTranscriptBoundary, recordTranscriptTaskEntry } from '../../conversations/sync-transcript.js';
+import { normalizeCodexRecord, verifyCodexTranscript } from './conversation-transcript.js';
+import { hookAdditionalContextToolResult } from '../../mcp/tool-result.js';
 import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -37,13 +42,26 @@ export async function codexStopLifecycleOutput(input, invoke) {
   return { decision: 'block', reason: boundedHookMessage(check.reason) };
 }
 
+export async function codexLifecycleOutput(event, input, invoke) {
+  if (event === 'Stop') return codexStopLifecycleOutput(input, invoke);
+  if (!input?.session_id || typeof input.cwd !== 'string' || typeof input.prompt !== 'string') {
+    throw new TypeError('Codex task entry requires session, cwd and prompt');
+  }
+  const context = await invoke('begin_task_context', { sessionId: input.session_id,
+    turnId: input.turn_id ?? null, projectPath: input.cwd, taskPrompt: input.prompt.slice(0, 8192),
+    sourceApplication: 'codex', sourceSessionId: input.session_id });
+  return JSON.parse(hookAdditionalContextToolResult(compactTaskContext(context), { hookEventName: event,
+    label: 'Fuli task context. Apply effective_preferences and checkpoint with taskContextToken.',
+    limitBytes: 128 * 1024, itemLimit: 1000 }).content[0].text);
+}
+
 export async function runCodexLifecycleHook(args, dependencies = {}) {
   const event = args[args.indexOf('--event') + 1];
-  if (event !== 'Stop') throw new TypeError('Missing Codex lifecycle event');
+  if (!['Stop', 'UserPromptSubmit'].includes(event)) throw new TypeError('Missing Codex lifecycle event');
   const input = await (dependencies.readInput ?? readHookInput)();
   const write = dependencies.write ?? ((value) => process.stdout.write(value));
   if (dependencies.invoke) {
-    const output = await codexStopLifecycleOutput(input, dependencies.invoke);
+    const output = await codexLifecycleOutput(event, input, dependencies.invoke);
     write(`${JSON.stringify(output)}\n`);
     return output;
   }
@@ -63,12 +81,33 @@ export async function runCodexLifecycleHook(args, dependencies = {}) {
       runtimeConfigPath
     });
     const invokeTool = dependencies.callTool ?? callAgentTool;
-    const output = await leases.withGraphLease('codex-lifecycle', () =>
-      codexStopLifecycleOutput(
-        input,
-        (name, parameters) => invokeTool(app, name, parameters)
-      )
-    );
+    const output = await leases.withGraphLease('codex-lifecycle', async () => {
+      try {
+        return await withTranscriptGuard(runtimeConfigPath, input, 'codex', app.getCapturePolicy?.().enabled, async guard => {
+          let sync = await syncConversationTranscript(app, input, 'codex', {
+            normalize: normalizeCodexRecord, verify: verifyCodexTranscript
+          }, guard);
+          if (event === 'UserPromptSubmit' && sync.entryBlocked) return { decision: 'block', reason: sync.reason };
+          const entryGuard = sync.status === 'capture_disabled' ? null : guard;
+          if (event === 'UserPromptSubmit' && entryGuard?.value) await entryGuard.write({ ...entryGuard.value, phase: 'beginning' });
+          const result = await codexLifecycleOutput(event, input, async (name, parameters) => {
+            const context = await invokeTool(app, name, parameters);
+            if (name === 'begin_task_context') await recordTranscriptTaskEntry(entryGuard, context);
+            return context;
+          });
+          if (event === 'UserPromptSubmit') sync = await claimTranscriptBoundary(app, input, 'codex', sync, {
+            normalize: normalizeCodexRecord, verify: verifyCodexTranscript
+          }, entryGuard);
+          if (event === 'UserPromptSubmit' && sync.entryBlocked) return { decision: 'block', reason: sync.reason };
+          return withTranscriptNotice(result, sync);
+        });
+      } catch (error) {
+        if (event !== 'UserPromptSubmit' || !app.getCapturePolicy?.().enabled || !input.transcript_path) throw error;
+        return { decision: 'block', reason: error.code === 'EADDRINUSE'
+          ? 'The session handoff lock is occupied. Retry after the current hook finishes; if it persists, start a new host session and resume the intended Agent.'
+          : 'Fuli transcript handoff could not be completed safely. Retry task entry; no previous Agent context was supplied.' };
+      }
+    });
     write(`${JSON.stringify(output)}\n`);
     return output;
   } finally {

package/src/agents/codex/lifecycle-hooks.js

@@ -18,8 +18,8 @@ export function withCodexLifecycleHooks(current, { timeout = 30, context = null
     }],
     ['Stop', 'verify_task_checkpoint', { sessionId: '${session_id}' }]
   ]) {
-    const handler = event === 'Stop' && context
-      ? { type: 'command', command: codexStopCommand(context), timeout }
+    const handler = context
+      ? { type: 'command', command: codexStopCommand(context, event), timeout }
       : { type: 'mcp_tool', server: 'fuli', tool, input, timeout };
     hooks[event] = [...(hooks[event] ?? []), { hooks: [handler] }];
   }
@@ -88,12 +88,12 @@ export function withCodexTomlLifecycleHooks(source, { timeout = 30, context = nu
   const lines = clean.replaceAll('\r\n', '\n').split('\n');
   while (lines.length && !lines.at(-1).trim()) lines.pop();
   const blocks = [
-    ...codexTomlHookBlock('UserPromptSubmit', 'begin_task_context', {
+    ...(context ? codexTomlCommandHookBlock('UserPromptSubmit', codexStopCommand(context, 'UserPromptSubmit'), timeout) : codexTomlHookBlock('UserPromptSubmit', 'begin_task_context', {
       sessionId: '${session_id}',
       turnId: '${turn_id}',
       projectPath: '${cwd}',
       taskPrompt: '${prompt}'
-    }, timeout),
+    }, timeout)),
     ...(context
       ? codexTomlCommandHookBlock('Stop', codexStopCommand(context), timeout)
       : codexTomlHookBlock('Stop', 'verify_task_checkpoint', {
@@ -212,7 +212,7 @@ function isManagedCodexHook(hook) {
       hook.command.includes(COMMAND_MARKER) && hook.command.includes('lifecycle-hook.js');
 }
 
-function codexStopCommand(context) {
+function codexStopCommand(context, event = 'Stop') {
   const script = context.codexLifecycleHookPath ??
     join(dirname(context.mcpServerPath), 'agents', 'codex', 'lifecycle-hook.js');
   return [
@@ -222,7 +222,7 @@ function codexStopCommand(context) {
     '--runtime-config',
     context.runtimeConfigPath,
     '--event',
-    'Stop'
+    event
   ].map(value => quoteShellArgument(value, context.platform)).join(' ');
 }
 

package/src/agents/cursor/lifecycle-hook.js

@@ -18,12 +18,13 @@ export async function cursorLifecycleOutput(event, input, invoke) {
   }
   const source = { sourceApplication: 'cursor', sourceSessionId: sessionId };
   if (event === 'stop') {
-    // Never restart a cancelled/error turn or loop indefinitely on an outage.
-    if (input.status !== 'completed' || (input.loop_count ?? 0) >= 2) return {};
+    // One host-counted continuation at most; never restart cancelled/error turns.
+    if (input.status !== 'completed' || (input.loop_count ?? 0) >= 1) return {};
     const check = await invoke('verify_task_checkpoint', { sessionId, ...source });
-    const reason = boundedHookMessage(check.reason);
+    const notice = '\nIf this mode is read-only or checkpoint writes are denied, state that the checkpoint was not saved and do not retry. This is the only checkpoint continuation.';
+    const reason = boundedHookMessage(check.reason, { maxBytes: 8_000 - Buffer.byteLength(notice, 'utf8') });
     return check.status === 'checkpoint_required' && reason.trim()
-      ? { followup_message: reason }
+      ? { followup_message: reason + notice }
       : {};
   }
   const roots = input.workspace_roots;

package/src/app/agent-request-context.js

@@ -1,3 +1,4 @@
+import { testToolsEnabled } from './test-tools.js';
 import { AsyncLocalStorage } from 'node:async_hooks';
 
 const requestContext = new AsyncLocalStorage();
@@ -8,7 +9,7 @@ export function runWithAgentRequestContext(value, operation) {
   }
   const signal = abortSignal(value?.signal);
   signal?.throwIfAborted();
-  return signal ? requestContext.run({ signal }, operation) : operation();
+  return requestContext.run({ signal, testToolsEnabled: value?.testToolsEnabled ?? testToolsEnabled() }, operation);
 }
 
 export function activeAgentRequestSignal() {
@@ -21,3 +22,7 @@ function abortSignal(value) {
     ? value
     : null;
 }
+
+export function activeTestToolsEnabled() {
+  return requestContext.getStore()?.testToolsEnabled ?? testToolsEnabled();
+}

package/src/app/test-tools.js

@@ -0,0 +1,26 @@
+import { ApplicationError, ApplicationErrorCode } from './application-error.js';
+
+/** Tools that must not appear on default production MCP surfaces. */
+export const TEST_ONLY_TOOL_NAMES = Object.freeze([
+  'cleanup_test_project_agents'
+]);
+
+const TEST_ONLY_TOOL_NAME_SET = new Set(TEST_ONLY_TOOL_NAMES);
+
+export function isTestOnlyToolName(name) {
+  return TEST_ONLY_TOOL_NAME_SET.has(name);
+}
+
+/** Opt-in via FULI_ENABLE_TEST_TOOLS=1|true for local harnesses and e2e. */
+export function testToolsEnabled(env = process.env) {
+  const value = env?.FULI_ENABLE_TEST_TOOLS;
+  return value === '1' || value === 'true';
+}
+
+export function assertTestToolsEnabled(env = process.env) {
+  if (testToolsEnabled(env)) return;
+  throw new ApplicationError(
+    ApplicationErrorCode.VALIDATION,
+    'cleanup_test_project_agents is disabled unless FULI_ENABLE_TEST_TOOLS=1'
+  );
+}

package/src/conversations/sync-transcript.js

@@ -0,0 +1,144 @@
+import { initialTranscriptBoundary, readTranscriptBatch } from './transcript-reader.js';
+import { transcriptDigest } from './transcript-guard.js';
+
+const pending = reason => ({ status: 'partial', entryBlocked: true, reason });
+const retryReason = 'Transcript handoff is pending. Retry task entry to continue its saved progress; no new Agent context was supplied';
+
+export async function syncConversationTranscript(application, input, sourceApplication, adapter, guard = null) {
+  if (!application.getCapturePolicy?.().enabled) return { status: 'capture_disabled' };
+  if (!input?.transcript_path) return { status: 'partial', reason: 'Host did not supply a visible transcript' };
+  let committedPages = 0;
+  try {
+    const task = await application.personal.currentTaskContext({ personal_space_id: application.config.personal.spaceId,
+      session_id: input.session_id, source_application: sourceApplication });
+    if (!task?.project_agent_id) return guard?.value ? pending(retryReason) : { status: 'unassigned' };
+    const scope = { personal_space_id: application.config.personal.spaceId, personal_project_id: task.personal_project_id,
+      agent_id: task.project_agent_id, source_application: sourceApplication };
+    const policy = await application.personal.conversation('query', { ...scope, mode: 'policy' });
+    if (!policy.enabled) return { status: 'capture_disabled' };
+    let session = await application.personal.conversation('query', { ...scope, mode: 'session', session_id: input.session_id });
+    if (!session.initialized) return guard?.value ? pending('Transcript initialization changed during handoff. Start a new host session and resume the intended Agent') : { status: 'partial', reason: 'Transcript capture needs a verified task entry boundary' };
+    if (guard?.value?.phase === 'claim') {
+      if (guard.value.nextOwner !== transcriptDigest(task.token)) return pending('Transcript task ownership changed during handoff. Start a new host session and resume the intended Agent');
+      await application.personal.conversation('boundary', { ...scope, session_id: input.session_id,
+        task_context_token: task.token, expected_cursor: guard.value.boundary, cursor: guard.value.boundary });
+      await guard.clear();
+    } else if (guard?.value && guard.value.owner !== transcriptDigest(task.token)) {
+      return pending('Transcript task ownership changed during handoff. Start a new host session and resume the intended Agent');
+    }
+    if (typeof input.prompt === 'string' && guard && !guard.value) {
+      await guard.write({ version: 1, phase: 'scan', owner: transcriptDigest(task.token),
+        prompt: transcriptDigest(input.prompt), scanCursor: session.cursor ?? 0, userMessages: 0, omitted: false });
+    }
+    if (guard?.value && typeof input.prompt === 'string' && guard.value.prompt !== transcriptDigest(input.prompt)) {
+      return pending('An earlier transcript handoff is pending. Retry the earlier task entry before sending a different prompt');
+    }
+    if (guard?.value?.phase === 'beginning') return pending('Task entry was interrupted before its new ownership was recorded. Start a new host session and resume the intended Agent; this uncertain native tail was not imported');
+    if (guard?.value?.phase === 'scan') {
+      for (let page = 0; page < 8; page++) {
+        const state = guard.value;
+        const batch = await readTranscriptBatch(input.transcript_path, input.session_id, state.scanCursor, adapter,
+          { stopBeforeDigest: state.prompt });
+        const next = { ...state, scanCursor: batch.cursor,
+          userMessages: state.userMessages + (batch.userMessages ?? 0), omitted: state.omitted || batch.omitted === true,
+          uncertainFrom: state.uncertainFrom ?? batch.uncertainFrom ?? null };
+        if (batch.atPromptBoundary) {
+          await guard.write({ ...next, scanCursor: batch.promptEndCursor,
+            candidate: batch.cursor, userMessages: next.userMessages + 1 });
+          continue;
+        }
+        // A repeated prompt in old backlog is not the new turn if visible
+        // messages follow it. Only the last visible prompt can prove a handoff.
+        if (batch.events.length) next.candidate = null;
+        // EOF is a prospective boundary only if no unverified user record or
+        // omitted fragment was traversed and the last native write is complete.
+        if (!batch.hasMore && batch.completeRecord && (Number.isSafeInteger(next.candidate) || (!next.userMessages && !next.omitted))) {
+          await guard.write({ ...next, phase: 'ready', boundary: next.candidate ?? batch.cursor });
+          break;
+        }
+        if (!batch.hasMore && next.uncertainFrom !== null) next.ambiguousFrom = next.uncertainFrom;
+        await guard.write(next);
+        if (!batch.hasMore) return pending('The current prompt could not be verified in native history. Retry after the host finishes writing; if it cannot record a blocked prompt, start a new host session and resume the intended Agent');
+        if (batch.cursor === state.scanCursor) return pending(retryReason);
+      }
+      if (guard.value.phase === 'scan') return pending(retryReason);
+    }
+    if (guard?.value && (session.cursor ?? 0) > guard.value.boundary) return pending('Transcript cursor moved beyond the verified handoff boundary; no scope was changed');
+    let result, userMessages = 0, omitted = false;
+    for (let page = 0; page < 8; page += 1) {
+      const batch = await readTranscriptBatch(input.transcript_path, input.session_id, session.cursor ?? 0, adapter,
+        guard?.value ? { stopAtCursor: Math.max(session.cursor ?? 0, guard.value.ambiguousFrom ?? guard.value.boundary) } : { stopBeforePrompt: input.prompt ?? null });
+      userMessages += batch.userMessages ?? 0; omitted ||= batch.omitted === true;
+      // Without a durable guard, an unmatched user record cannot be attributed
+      // to the prior owner merely because the file currently ends after it.
+      if (!guard && typeof input.prompt === 'string' && userMessages && !batch.atPromptBoundary) return pending(retryReason);
+      result = await application.personal.conversation('append', { ...scope, session_id: input.session_id,
+        task_context_token: task.token, events: batch.events, expected_cursor: session.cursor ?? 0, cursor: batch.cursor });
+      if (result.status === 'saved') committedPages++;
+      if (!batch.hasMore && guard?.value?.ambiguousFrom !== undefined && batch.cursor < guard.value.boundary) {
+        const boundary = guard.value.boundary;
+        result = await application.personal.conversation('append', { ...scope, session_id: input.session_id,
+          task_context_token: task.token, expected_cursor: batch.cursor, cursor: boundary,
+          events: [{ event_id: `jsonl-v1:${batch.cursor}:${boundary}:ambiguous`, role: 'tool', kind: 'tool_result',
+            content: '[Visible transcript content omitted: ambiguous task ownership; original remains in native history.]' }] });
+        batch.cursor = boundary;
+      }
+      if (!batch.hasMore) return { ...result, cursor: batch.cursor,
+        atPromptBoundary: Boolean(guard?.value || batch.atPromptBoundary || (typeof input.prompt === 'string' && !userMessages && !omitted && batch.completeRecord)),
+        entryBlocked: Boolean(guard?.value && typeof input.prompt !== 'string'),
+        coverage: 'supported_visible_events', parser: 'jsonl-v1', ...(guard?.value && typeof input.prompt !== 'string' ? { reason: retryReason } : {}) };
+      if (batch.cursor === (session.cursor ?? 0)) break;
+      session = { ...session, cursor: batch.cursor };
+    }
+    return pending(retryReason);
+  } catch {
+    return { status: committedPages ? 'partial' : 'unsaved', entryBlocked: typeof input.prompt === 'string',
+      reason: committedPages ? 'Some transcript pages were saved before capture failed; the next hook resumes from committed progress'
+        : 'Visible transcript capture could not be confirmed; native history will be retried at the next hook' };
+  }
+}
+
+export async function recordTranscriptTaskEntry(guard, context) {
+  if (!guard?.value) return;
+  const token = context?.taskContextToken ?? context?.task_context_token;
+  if (typeof token !== 'string' || !token) throw new Error('Task entry did not return its ownership token');
+  await guard.write({ ...guard.value, phase: 'claim', nextOwner: transcriptDigest(token) });
+}
+
+export function withTranscriptNotice(output, sync) {
+  if (!sync?.entryBlocked && !['unsaved', 'partial'].includes(sync?.status)) return output;
+  return { ...output, systemMessage: [output.systemMessage, `Fuli: ${sync.reason}.`].filter(Boolean).join('\n') };
+}
+
+// A scope switch is safe only after the old scope was flushed up to the current
+// prompt. Failed flushes keep the old owner, so new Agents cannot inherit an
+// unrelated session tail. Native files remain available for explicit recovery.
+export async function claimTranscriptBoundary(application, input, sourceApplication, sync, adapter, guard = null) {
+  if (!application.getCapturePolicy?.().enabled || !input.transcript_path) return sync;
+  try {
+    const task = await application.personal.currentTaskContext({ personal_space_id: application.config.personal.spaceId,
+      session_id: input.session_id, source_application: sourceApplication });
+    if (!task?.project_agent_id) return sync;
+    if (guard?.value && (guard.value.phase !== 'claim' || guard.value.nextOwner !== transcriptDigest(task.token))) return pending('Transcript claim does not match the task entry that created it');
+    const scope = { personal_space_id: application.config.personal.spaceId,
+      personal_project_id: task.personal_project_id, agent_id: task.project_agent_id,
+      source_application: sourceApplication, session_id: input.session_id };
+    const policy = await application.personal.conversation('query', { ...scope, mode: 'policy' });
+    if (!policy.enabled) return { status: 'capture_disabled' };
+    const session = await application.personal.conversation('query', { ...scope, mode: 'session' });
+    if (!session.initialized) {
+      const cursor = await initialTranscriptBoundary(input.transcript_path, input.session_id, input.prompt, adapter);
+      await application.personal.conversation('boundary', { ...scope, task_context_token: task.token,
+        expected_cursor: 0, cursor, initialize_cursor: true });
+      return { status: 'ready', coverage: 'from_current_task' };
+    }
+    if (sync?.status === 'saved' && sync.atPromptBoundary) {
+      await application.personal.conversation('boundary', { ...scope, task_context_token: task.token,
+        expected_cursor: sync.cursor, cursor: sync.cursor });
+      await guard?.clear();
+    }
+    return sync;
+  } catch {
+    return { status: 'unsaved', entryBlocked: true, reason: 'Transcript boundary is unverified; saved task context is still available' };
+  }
+}

package/src/conversations/task-context-view.js

@@ -0,0 +1,28 @@
+// Preserve every effective instruction; remove evidence envelopes from the hot
+// path. Full records remain available through explicit read tools.
+export function compactTaskContext(value) {
+  if (!value || typeof value !== 'object') return value;
+  const result = { ...value };
+  if (Array.isArray(value.effective_preferences)) result.effective_preferences = value.effective_preferences.map(item => ({
+    instruction: item.instruction, preference_key: item.preference_key,
+    preference_scope: item.preference_scope, confirmation_status: item.confirmation_status
+  }));
+  const continuity = value.project_agent_context;
+  if (continuity?.memory) {
+    const memory = continuity.memory;
+    const current = memory.current;
+    const notes = current?.memory;
+    result.project_agent_context = { ...continuity, knowledge: undefined, recent_tasks: undefined,
+      memory: { ...memory, history: undefined, workLog: undefined,
+        current: current && { ...current, memory: notes && {
+          summary: notes.summary?.slice(0, 800),
+          decisions: notes.decisions?.slice(0, 3).map(note => note.slice(0, 160)),
+          openThreads: notes.openThreads?.slice(0, 3).map(note => note.slice(0, 160)),
+          nextActions: notes.nextActions?.slice(0, 3).map(note => note.slice(0, 160))
+        } },
+        view: 'preview', requiresFullReadBeforeWrite: true,
+        guidance: 'Use get_project_agent_memory before merging or checkpointing working memory; this preview omits history and may truncate notes.'
+      } };
+  }
+  return result;
+}

package/src/conversations/transcript-guard.js

@@ -0,0 +1,54 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, open, readFile, rename, rm, lstat } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { createServer } from 'node:net';
+
+export const transcriptDigest = value => createHash('sha256').update(value).digest('hex');
+
+// Only opaque hashes and byte offsets are stored locally. The per-session lock
+// covers scan, begin, and claim; a second hook must retry rather than race it.
+export async function withTranscriptGuard(runtimeConfigPath, input, source, enabled, operation) {
+  if (!enabled || !input?.transcript_path || !input?.session_id) return operation(null);
+  const directory = join(dirname(runtimeConfigPath), 'transcript-guards');
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  if (!(await lstat(directory)).isDirectory()) throw new Error('Transcript guard directory is unavailable');
+  const key = transcriptDigest(`${runtimeConfigPath}\0${source}\0${input.session_id}`);
+  const path = join(directory, `${key}.json`);
+  // A loopback mutex is released by the OS even if the process is killed.
+  // Port collisions fail closed and request a retry; no transcript is served.
+  const lock = createServer(socket => socket.destroy());
+  const lockKey = transcriptDigest(`${directory}\0${key}`);
+  const port = 49152 + (parseInt(lockKey.slice(0, 8), 16) % 16384);
+  await new Promise((resolve, reject) => {
+    lock.once('error', reject);
+    lock.listen({ host: '127.0.0.1', port, exclusive: true }, resolve);
+  });
+  try {
+    let value = null;
+    try {
+      if (!(await lstat(path)).isFile()) throw new Error('Invalid transcript guard');
+      value = JSON.parse(await readFile(path, 'utf8'));
+      if (value.version !== 1 || !['scan', 'ready', 'beginning', 'claim'].includes(value.phase)
+        || !/^[a-f0-9]{64}$/.test(value.owner ?? '') || !/^[a-f0-9]{64}$/.test(value.prompt ?? '')
+        || !Number.isSafeInteger(value.scanCursor) || value.scanCursor < 0
+        || (value.boundary !== undefined && (!Number.isSafeInteger(value.boundary) || value.boundary < 0))) {
+        throw new Error('Invalid transcript guard state');
+      }
+    } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    const guard = {
+      get value() { return value; },
+      async write(next) {
+        const temporary = `${path}.${randomUUID()}`;
+        try {
+          const file = await open(temporary, 'wx', 0o600);
+          try { await file.writeFile(JSON.stringify(next)); await file.sync(); }
+          finally { await file.close(); }
+          await rename(temporary, path);
+          value = next;
+        } finally { await rm(temporary, { force: true }); }
+      },
+      async clear() { await rm(path, { force: true }); value = null; }
+    };
+    return await operation(guard);
+  } finally { await new Promise(resolve => lock.close(resolve)); }
+}