ethagent 3.3.4 → 4.0.0

package/src/cli/demo.ts

@@ -0,0 +1,86 @@
+import type { EthagentConfig } from '../storage/config.js'
+import type { AgentReconciliation } from '../identity/manager/shared/reconciliation/index.js'
+
+const DEMO_ENV = 'ETHAGENT_DEMO'
+
+export function isDemoMode(): boolean {
+  return process.env[DEMO_ENV] === '1'
+}
+
+export function enableDemoMode(): void {
+  process.env[DEMO_ENV] = '1'
+}
+
+const DEMO_OWNER = '0xA1E977e700bF82019beb381F1582575303A389CE' as const
+const DEMO_AGENT_ADDRESS = '0x6bdC52c8e262c6D139e618260400614c2Bfe51d7' as const
+const DEMO_REGISTRY = '0x8004A169FB4a3325136EB29fA0ceB6D2e539a432' as const
+const DEMO_AGENT_ID = '42'
+const DEMO_AGENT_URI = 'ipfs://bafkreidemodemodemodemodemodemodemodemodemodemodemo'
+const DEMO_BACKUP_CID = 'bafkreidemodemodemodemodemodemodemodemodemodemodemo'
+const DEMO_AGENT_CARD_CID = 'bafkreidemoagentcarddemoagentcarddemoagentcarddemoag'
+const DEMO_CREATED_AT = '2026-01-01T00:00:00.000Z'
+
+export function synthDemoConfig(): EthagentConfig {
+  return {
+    version: 2,
+    firstSeenAt: DEMO_CREATED_AT,
+    selectedNetwork: 'base',
+    erc8004: {
+      chainId: 8453,
+      rpcUrl: 'https://mainnet.base.org',
+      identityRegistryAddress: DEMO_REGISTRY,
+    },
+    identity: {
+      source: 'erc8004',
+      address: DEMO_AGENT_ADDRESS,
+      ownerAddress: DEMO_OWNER,
+      connectedWallet: DEMO_OWNER,
+      createdAt: DEMO_CREATED_AT,
+      chainId: 8453,
+      rpcUrl: 'https://mainnet.base.org',
+      identityRegistryAddress: DEMO_REGISTRY,
+      agentId: DEMO_AGENT_ID,
+      agentUri: DEMO_AGENT_URI,
+      metadataCid: DEMO_AGENT_URI.replace('ipfs://', ''),
+      state: { name: 'demo agent', custodyMode: 'simple' },
+      backup: {
+        cid: DEMO_BACKUP_CID,
+        createdAt: DEMO_CREATED_AT,
+        envelopeVersion: 'ethagent-continuity-snapshot-v1',
+        ipfsApiUrl: 'https://uploads.pinata.cloud/v3/files',
+        status: 'pinned',
+        ownerAddress: DEMO_OWNER,
+        chainId: 8453,
+        rpcUrl: 'https://mainnet.base.org',
+        identityRegistryAddress: DEMO_REGISTRY,
+        agentId: DEMO_AGENT_ID,
+        agentUri: DEMO_AGENT_URI,
+        metadataCid: DEMO_AGENT_URI.replace('ipfs://', ''),
+      },
+      agentCard: {
+        cid: DEMO_AGENT_CARD_CID,
+        updatedAt: DEMO_CREATED_AT,
+        status: 'pinned',
+      },
+    },
+  }
+}
+
+export function synthDemoReconciliation(): AgentReconciliation {
+  return {
+    token: 'linked',
+    tokenAgentId: DEMO_AGENT_ID,
+    onChainOwner: DEMO_OWNER,
+    custody: 'simple',
+    agentUri: 'in-sync',
+    vault: 'unset',
+    workingTree: 'clean',
+    rpc: 'reachable',
+    driftCount: 0,
+    lastCheckedAt: new Date().toISOString(),
+  }
+}
+
+export function demoNotice(label: string): string {
+  return `demo mode: would have ${label}`
+}

package/src/cli/hookIo.ts

@@ -0,0 +1,45 @@
+import path from 'node:path'
+
+// Shared helpers for the Claude Code hook entrypoints (--sync-on-edit, --memory-guard).
+// A hook receives the harness payload as JSON on stdin and may answer with JSON on stdout.
+
+export async function readHookPayload(): Promise<Record<string, unknown> | null> {
+  if (process.stdin.isTTY) return null
+  let raw = ''
+  try {
+    process.stdin.setEncoding('utf8')
+    for await (const chunk of process.stdin) raw += chunk
+  } catch {
+    return null
+  }
+  raw = raw.trim()
+  if (!raw) return null
+  try {
+    const parsed = JSON.parse(raw) as unknown
+    return parsed && typeof parsed === 'object' ? (parsed as Record<string, unknown>) : null
+  } catch {
+    return null
+  }
+}
+
+export function hookFilePath(payload: Record<string, unknown> | null): string | null {
+  const filePath = (payload?.tool_input as { file_path?: unknown } | undefined)?.file_path
+  return typeof filePath === 'string' && filePath.length > 0 ? filePath : null
+}
+
+export function samePath(a: string, b: string): boolean {
+  const na = path.resolve(a)
+  const nb = path.resolve(b)
+  return process.platform === 'win32' ? na.toLowerCase() === nb.toLowerCase() : na === nb
+}
+
+// True when `file` is `dir` itself or sits anywhere beneath it. Compares on a
+// separator boundary so `.../memory` does not match a sibling like `.../memory-notes`.
+export function isWithinDir(dir: string, file: string): boolean {
+  const fold = (p: string): string => (process.platform === 'win32' ? p.toLowerCase() : p)
+  const nd = fold(path.resolve(dir))
+  const nf = fold(path.resolve(file))
+  if (nd === nf) return true
+  const prefix = nd.endsWith(path.sep) ? nd : nd + path.sep
+  return nf.startsWith(prefix)
+}

package/src/cli/main.tsx

@@ -5,16 +5,18 @@ import fs from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { theme } from '../ui/theme.js'
-import { FirstRun } from '../app/FirstRun.js'
-import { ChatScreen } from '../chat/ChatScreen.js'
+import { Spinner } from '../ui/Spinner.js'
 import { KeybindingProvider } from '../app/keybindings/KeybindingProvider.js'
-import { AppInputProvider, useAppInput } from '../app/input/AppInputProvider.js'
-import { loadConfig, type EthagentConfig } from '../storage/config.js'
+import { AppInputProvider } from '../app/input/AppInputProvider.js'
+import { IdentityManager } from '../identity/manager/IdentityManager.js'
+import type { IdentityManagerResult } from '../identity/manager/IdentityManager.js'
+import { loadConfig, saveConfig, type EthagentConfig } from '../storage/config.js'
+import { runSync, runSyncList, runSyncOnEdit } from './sync.js'
+import { runMemoryGuard } from './memoryGuard.js'
+import { runSessionStart } from './sessionStart.js'
+import { runStatus } from './status.js'
 import { runResetCommand } from './reset.js'
-import { runPreviewCommand } from './preview.js'
-import { checkForUpdates } from './updateNotice.js'
-import { Spinner } from '../ui/Spinner.js'
-import { TITLE_STATIC, clearTerminalTitle, setTerminalTitle } from '../ui/terminalTitle.js'
+import { enableDemoMode, synthDemoConfig } from './demo.js'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 
@@ -33,173 +35,142 @@ function printHelp(): void {
     'ethagent: privacy-first AI agent with a portable Ethereum identity',
     '',
     'usage:',
-    '  ethagent             start the agent (first run triggers setup)',
-    '  ethagent preview     show the brand splash and exit',
-    '  ethagent reset       factory reset local data (local LLMs kept)',
-    '  ethagent reset --yes run reset without the confirm prompt',
-    '  ethagent --version   print version',
-    '  ethagent --help      print this help',
+    '  ethagent                    manage identity',
+    '  ethagent reset              delete local identity, continuity, and secrets',
+    '  ethagent --sync             sync soul, memory, and skills to every harness',
+    '  ethagent --sync-list        list sync adapters and which ones detect here',
+    '  ethagent --demo             walk identity with synthetic data',
+    '  ethagent --status           print one-line identity summary',
+    '  ethagent --version          print version',
+    '  ethagent --help             print this help',
     '',
-    'inside the agent, type /help for slash commands.',
+    'plugin hooks (invoked automatically, not meant to be run by hand):',
+    '  ethagent --session-start    sync, then tell the agent where to record memory',
+    '  ethagent --memory-guard     keep agent memory in the portable markers, not local notes',
   ]
   for (const line of lines) process.stdout.write(line + '\n')
 }
 
-type AppPhase =
+type Phase =
   | { kind: 'loading' }
-  | { kind: 'setup' }
-  | { kind: 'ready'; config: EthagentConfig }
-  | { kind: 'cancelled' }
+  | { kind: 'ready'; config: EthagentConfig | null }
   | { kind: 'error'; message: string }
 
-const MIN_STARTUP_SPINNER_MS = 480
-
-function delay(ms: number): Promise<void> {
-  return new Promise(resolve => setTimeout(resolve, ms))
+type RootProps = {
+  setExit: (n: number) => void
+  initialConfig: EthagentConfig | null | undefined
 }
 
-const AppRoot: React.FC<{ setExitCode: (code: number) => void; currentVersion: string }> = ({ setExitCode, currentVersion }) => {
-  const [phase, setPhase] = useState<AppPhase>({ kind: 'loading' })
-  const [updateNotice, setUpdateNotice] = useState<string | null>(null)
+const Root: React.FC<RootProps> = ({ setExit, initialConfig }) => {
+  const [phase, setPhase] = useState<Phase>(
+    initialConfig !== undefined
+      ? { kind: 'ready', config: initialConfig }
+      : { kind: 'loading' },
+  )
   const { exit } = useApp()
 
   useEffect(() => {
     if (phase.kind !== 'loading') return
     let cancelled = false
-    Promise.all([loadConfig(), delay(MIN_STARTUP_SPINNER_MS)])
-      .then(config => {
-        if (cancelled) return
-        setPhase(config[0] ? { kind: 'ready', config: config[0] } : { kind: 'setup' })
-      })
-      .catch((err: unknown) => {
-        if (cancelled) return
-        setPhase({ kind: 'error', message: (err as Error).message })
-      })
+    loadConfig()
+      .then(c => { if (!cancelled) setPhase({ kind: 'ready', config: c }) })
+      .catch(err => { if (!cancelled) setPhase({ kind: 'error', message: (err as Error).message }) })
     return () => { cancelled = true }
-  }, [phase])
-
-  useEffect(() => {
-    let cancelled = false
-    void checkForUpdates(currentVersion)
-      .then(notice => {
-        if (!cancelled) setUpdateNotice(notice)
-      })
-      .catch(() => {})
-    return () => { cancelled = true }
-  }, [currentVersion])
-
-  useEffect(() => {
-    setTerminalTitle(TITLE_STATIC)
-  }, [])
-
-  useEffect(() => {
-    if (phase.kind === 'cancelled') {
-      setExitCode(1)
-      const t = setTimeout(() => exit(), 10)
-      return () => clearTimeout(t)
-    }
-    if (phase.kind === 'error') {
-      setExitCode(1)
-      const t = setTimeout(() => exit(), 10)
-      return () => clearTimeout(t)
-    }
-    return undefined
-  }, [phase, exit, setExitCode])
-
-  useAppInput((input, key) => {
-    if (phase.kind === 'ready') return
-    if (key.ctrl && (input === 'c' || input === 'd')) {
-      if (phase.kind === 'setup') {
-        setPhase({ kind: 'cancelled' })
-      } else {
-        exit()
-      }
-    }
-  })
+  }, [phase.kind])
 
   if (phase.kind === 'loading') {
-    return (
-      <Box padding={1}>
-        <Spinner label="starting ethagent..." showElapsed={false} />
-      </Box>
-    )
+    return <Box padding={1}><Spinner label="loading identity..." showElapsed={false} /></Box>
   }
-  if (phase.kind === 'setup') {
-    return (
-      <FirstRun
-        onComplete={config => setPhase({ kind: 'ready', config })}
-        onCancel={() => setPhase({ kind: 'cancelled' })}
-      />
-    )
+  if (phase.kind === 'error') {
+    return <Box padding={1}><Text color={theme.accentError}>Error: {phase.message}</Text></Box>
   }
-  if (phase.kind === 'cancelled') {
-    return (
-      <Box padding={1}>
-        <Text color={theme.dim}>Setup cancelled.</Text>
-      </Box>
-    )
+
+  const mode = phase.config?.identity ? 'manage' : 'first-run'
+  const handleComplete = (result: IdentityManagerResult): void => {
+    setExit(result.kind === 'cancel' ? 1 : 0)
+    setTimeout(() => exit(), 10)
   }
-  if (phase.kind === 'error') {
-    return (
-      <Box padding={1}>
-        <Text color={theme.accentError}>Error: {phase.message}</Text>
-      </Box>
-    )
+  const handleConfigChange = (next: EthagentConfig): void => {
+    setPhase({ kind: 'ready', config: next })
+    void saveConfig(next)
   }
+
   return (
-    <ChatScreen
-      config={phase.config}
-      onReplaceConfig={next => setPhase({ kind: 'ready', config: next })}
-      updateNotice={updateNotice}
+    <IdentityManager
+      mode={mode}
+      {...(phase.config ? { config: phase.config } : {})}
+      onConfigChange={handleConfigChange}
+      onComplete={handleComplete}
     />
   )
 }
 
-async function runDefault(currentVersion: string): Promise<number> {
+async function renderHub(initialConfig: EthagentConfig | null | undefined): Promise<number> {
   let exitCode = 0
-  setTerminalTitle(TITLE_STATIC)
-  process.once('exit', clearTerminalTitle)
   const instance = render(
     <AppInputProvider>
       <KeybindingProvider>
-        <AppRoot setExitCode={code => { exitCode = code }} currentVersion={currentVersion} />
+        <Root setExit={n => { exitCode = n }} initialConfig={initialConfig} />
       </KeybindingProvider>
     </AppInputProvider>,
-    {
-      exitOnCtrlC: false,
-    },
+    { exitOnCtrlC: false },
   )
+  const guard = (reason: unknown): void => {
+    const message = reason instanceof Error ? reason.message : String(reason)
+    process.stderr.write(`background error: ${message}\n`)
+  }
+  const onUnhandledRejection = (reason: unknown): void => guard(reason)
+  const onUncaughtException = (err: unknown): void => guard(err)
+  process.on('unhandledRejection', onUnhandledRejection)
+  process.on('uncaughtException', onUncaughtException)
   try {
     await instance.waitUntilExit()
   } catch {
     exitCode = 1
+  } finally {
+    process.removeListener('unhandledRejection', onUnhandledRejection)
+    process.removeListener('uncaughtException', onUncaughtException)
   }
   return exitCode
 }
 
 async function main(): Promise<number> {
   const argv = process.argv.slice(2)
-  const [cmd, ...rest] = argv
+  const flags = new Set(argv)
+  const version = readVersion()
 
-  if (!cmd) return runDefault(readVersion())
-  if (cmd === '--version' || cmd === '-v') {
-    process.stdout.write(`ethagent ${readVersion()}\n`)
+  if (flags.has('--version') || flags.has('-v')) {
+    process.stdout.write(`ethagent ${version}\n`)
     return 0
   }
-  if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
+  if (flags.has('--help') || flags.has('-h') || argv[0] === 'help') {
     printHelp()
     return 0
   }
+  if (flags.has('--sync-on-edit')) return runSyncOnEdit()
+  if (flags.has('--session-start')) return runSessionStart()
+  if (flags.has('--memory-guard')) return runMemoryGuard()
+  if (flags.has('--sync-list')) return runSyncList()
+  if (flags.has('--sync')) return runSync()
+  if (flags.has('--status')) return runStatus(version)
+  if (flags.has('--demo')) {
+    enableDemoMode()
+    return renderHub(synthDemoConfig())
+  }
+  if (argv[0] === 'reset') return runResetCommand(argv.slice(1))
 
-  switch (cmd) {
-    case 'preview':
-      return runPreviewCommand()
-    case 'reset':
-      return runResetCommand(rest)
-    default:
-      process.stderr.write(`unknown command: ${cmd}\nrun 'ethagent --help' for usage\n`)
-      return 2
+  const unknown = argv.find(a => a.startsWith('-'))
+  if (unknown && !flags.has('--demo')) {
+    process.stderr.write(`unknown flag: ${unknown}\nrun 'ethagent --help' for usage\n`)
+    return 2
   }
+  const positional = argv[0]
+  if (positional) {
+    process.stderr.write(`unknown command: ${positional}\nrun 'ethagent --help' for usage\n`)
+    return 2
+  }
+
+  return renderHub(undefined)
 }
 
 main()

package/src/cli/memoryGuard.ts

@@ -0,0 +1,49 @@
+import { loadConfig } from '../storage/config.js'
+import { hookFilePath, isWithinDir, readHookPayload } from './hookIo.js'
+import { claudeCodeNativeMemoryDir } from './syncAdapters/claude-code.js'
+
+// Shown to the model when it tries to write into the harness-native memory dir.
+// The redirect points at a different file (~/.claude/CLAUDE.md), so the model's
+// next attempt succeeds and there is no deny loop.
+export const MEMORY_REDIRECT_REASON =
+  "ethagent manages this agent's portable memory. Don't write to the Claude Code native memory directory; " +
+  'those files stay on this machine and never reach your onchain vault. Record durable facts by editing ' +
+  '~/.claude/CLAUDE.md instead: put user and project facts between the `<!-- ethagent:memory:start -->` and ' +
+  '`<!-- ethagent:memory:end -->` markers, and persona, voice, and standards between the ' +
+  '`<!-- ethagent:soul:start -->` and `<!-- ethagent:soul:end -->` markers. Those edits sync to your vault automatically.'
+
+export function decideMemoryGuard(
+  filePath: string | null | undefined,
+  opts: { identityPresent: boolean },
+): { deny: boolean; reason?: string } {
+  if (!opts.identityPresent) return { deny: false }
+  if (!filePath) return { deny: false }
+  if (isWithinDir(claudeCodeNativeMemoryDir(), filePath)) {
+    return { deny: true, reason: MEMORY_REDIRECT_REASON }
+  }
+  return { deny: false }
+}
+
+// PreToolUse hook for Edit|Write|MultiEdit. Fail-open: any error or missing
+// identity allows the write, so the guard never wedges unrelated projects.
+export async function runMemoryGuard(): Promise<number> {
+  try {
+    const config = await loadConfig()
+    const filePath = hookFilePath(await readHookPayload())
+    const decision = decideMemoryGuard(filePath, { identityPresent: !!config?.identity })
+    if (decision.deny) {
+      process.stdout.write(
+        JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: 'deny',
+            permissionDecisionReason: decision.reason,
+          },
+        }) + '\n',
+      )
+    }
+  } catch {
+    // fail open
+  }
+  return 0
+}

package/src/cli/reset.ts

@@ -1,84 +1,58 @@
-import { createInterface } from 'node:readline/promises'
-import { stdin as processStdin, stdout as processStdout, stderr as processStderr } from 'node:process'
 import React from 'react'
 import { render } from 'ink'
-import {
-  createFactoryResetPlan,
-  formatFactoryResetPlan,
-  runFactoryReset,
-  type FactoryResetPlan,
-} from '../storage/factoryReset.js'
+import { stdout, stderr } from 'node:process'
 import { AppInputProvider } from '../app/input/AppInputProvider.js'
 import { ResetConfirmView } from './ResetConfirmView.js'
+import { resetPlan, runReset } from '../storage/reset.js'
+import { clearHarnessManagedBlocks } from './syncAdapters/index.js'
 
-export type ResetCommandIO = {
-  write?: (text: string) => void
-  writeError?: (text: string) => void
-  readConfirmation?: () => Promise<string>
-  clearSecrets?: boolean
-  input?: NodeJS.ReadableStream
-  output?: NodeJS.WritableStream
-}
-
-export async function runResetCommand(args: string[] = [], io: ResetCommandIO = {}): Promise<number> {
-  const write = io.write ?? (text => { processStdout.write(text) })
-  const writeError = io.writeError ?? (text => { processStderr.write(text) })
+export async function runResetCommand(args: string[] = []): Promise<number> {
   const yes = args.includes('--yes') || args.includes('-y')
-  const unknown = args.filter(arg => arg !== '--yes' && arg !== '-y')
+  const unknown = args.filter(a => a !== '--yes' && a !== '-y')
   if (unknown.length > 0) {
-    writeError(`unknown reset option: ${unknown[0]}\nusage: ethagent reset [--yes]\n`)
+    stderr.write(`unknown reset option: ${unknown[0]}\nusage: ethagent reset [--yes]\n`)
     return 2
   }
 
-  const plan = await createFactoryResetPlan()
+  const plan = resetPlan()
 
-  if (!yes) {
-    const confirmed = io.readConfirmation
-      ? await readTextConfirmation(plan, io)
-      : await readInkConfirmation(plan, io)
-    if (!confirmed) {
-      write('Reset Cancelled.\n')
-      return 1
-    }
-  } else {
-    write(`${formatFactoryResetPlan(plan)}\n`)
+  if (yes) {
+    stdout.write(`Resetting ethagent: ${plan.configDir} and ${plan.secretAccounts.length} secrets.\n`)
+    await runReset()
+    await finishReset()
+    return 0
   }
 
-  const result = await runFactoryReset({ clearSecrets: io.clearSecrets })
-  write([
-    'Reset Complete.',
-    `Deleted ${result.deletedPaths.length} local path${result.deletedPaths.length === 1 ? '' : 's'}.`,
-    `Cleared ${result.clearedSecretAccounts.length} secret account${result.clearedSecretAccounts.length === 1 ? '' : 's'}.`,
-    result.preservedPaths.length > 0
-      ? `Kept ${result.preservedPaths.length} local model path${result.preservedPaths.length === 1 ? '' : 's'}.`
-      : 'Kept no local model assets.',
-    '',
-  ].join('\n'))
+  const confirmed = await confirmWithInk(plan.configDir, plan.secretAccounts)
+  if (!confirmed) {
+    stdout.write('Reset cancelled.\n')
+    return 1
+  }
+  await runReset()
+  await finishReset()
   return 0
 }
 
-async function readTextConfirmation(plan: FactoryResetPlan, io: ResetCommandIO): Promise<boolean> {
-  ;(io.write ?? (text => { processStdout.write(text) }))(`${formatFactoryResetPlan(plan)}\n`)
-  const answer = await readConfirmation(io)
-  return answer.trim().toLowerCase() === 'confirm'
+async function finishReset(): Promise<void> {
+  const cleared = await clearHarnessManagedBlocks()
+  if (cleared.length > 0) {
+    stdout.write(`Cleared ethagent markers from ${cleared.length} file${cleared.length === 1 ? '' : 's'}.\n`)
+  }
+  stdout.write('Reset complete. Run ethagent to create or link an agent identity.\n')
 }
 
-async function readInkConfirmation(plan: FactoryResetPlan, io: ResetCommandIO): Promise<boolean> {
+async function confirmWithInk(configDir: string, secretAccounts: string[]): Promise<boolean> {
   let confirmed = false
   const instance = render(
     React.createElement(
       AppInputProvider,
       null,
       React.createElement(ResetConfirmView, {
-        plan,
+        plan: { configDir, secretAccounts },
         onDone: (value: boolean) => { confirmed = value },
       }),
     ),
-    {
-      exitOnCtrlC: false,
-      stdin: (io.input ?? processStdin) as typeof processStdin,
-      stdout: (io.output ?? processStdout) as typeof processStdout,
-    },
+    { exitOnCtrlC: false },
   )
   try {
     await instance.waitUntilExit()
@@ -87,19 +61,3 @@ async function readInkConfirmation(plan: FactoryResetPlan, io: ResetCommandIO):
   }
   return confirmed
 }
-
-async function readConfirmation(io: ResetCommandIO): Promise<string> {
-  if (io.readConfirmation) {
-    return io.readConfirmation()
-  }
-
-  const rl = createInterface({
-    input: io.input ?? processStdin,
-    output: io.output ?? processStdout,
-  })
-  try {
-    return await rl.question('Confirm reset: ')
-  } finally {
-    rl.close()
-  }
-}

package/src/cli/sessionStart.ts

@@ -0,0 +1,33 @@
+import { runSync } from './sync.js'
+
+// Injected into the model's context on session start so it records durable facts
+// in the portable markers (which sync to the vault) instead of harness-local files.
+export function buildSessionStartContext(): string {
+  return (
+    "ethagent portable memory is active. As you converse, keep this agent's soul and memory current by editing " +
+    '~/.claude/CLAUDE.md directly: durable user and project facts go between the `<!-- ethagent:memory:start -->` and ' +
+    '`<!-- ethagent:memory:end -->` markers; persona, voice, and standards go between the `<!-- ethagent:soul:start -->` ' +
+    'and `<!-- ethagent:soul:end -->` markers. Do NOT create separate files in the Claude Code native memory directory ' +
+    '(~/.claude/projects/.../memory/), since they do not travel with the agent. Edits between the markers sync to the ' +
+    'onchain vault automatically.'
+  )
+}
+
+// SessionStart hook: restore (sync vault -> harness) then remind (inject guidance).
+// runSync is quiet here so only the JSON envelope reaches stdout for the harness to parse.
+export async function runSessionStart(): Promise<number> {
+  try {
+    await runSync({ quiet: true })
+  } catch {
+    // still emit guidance even if the sync step failed
+  }
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'SessionStart',
+        additionalContext: buildSessionStartContext(),
+      },
+    }) + '\n',
+  )
+  return 0
+}