Merge remote-tracking branch 'origin/main' into auth-profile-rotation

# Conflicts: # pnpm-lock.yaml # src/agent/runner.ts
2026-02-03 17:58:50 +08:00 · 2026-02-03 17:58:50 +08:00 · 4b10420324
commit 4b10420324
parent e8815dbb97 de686022c3
62 changed files with 9639 additions and 81 deletions
--- a/apps/mobile/.gitignore
+++ b/apps/mobile/.gitignore
@ -0,0 +1,43 @@
+# Learn more https://docs.github.com/en/get-started/getting-started-with-git/ignoring-files
+
+# dependencies
+node_modules/
+
+# Expo
+.expo/
+dist/
+web-build/
+expo-env.d.ts
+
+# Native
+.kotlin/
+*.orig.*
+*.jks
+*.p8
+*.p12
+*.key
+*.mobileprovision
+
+# Metro
+.metro-health-check*
+
+# debug
+npm-debug.*
+yarn-debug.*
+yarn-error.*
+
+# macOS
+.DS_Store
+*.pem
+
+# local env files
+.env*.local
+
+# typescript
+*.tsbuildinfo
+
+app-example
+
+# generated native folders
+/ios
+/android
--- a/apps/mobile/.vscode/extensions.json
+++ b/apps/mobile/.vscode/extensions.json
@ -0,0 +1 @@
+{ "recommendations": ["expo.vscode-expo-tools"] }
--- a/apps/mobile/.vscode/settings.json
+++ b/apps/mobile/.vscode/settings.json
@ -0,0 +1,7 @@
+{
+  "editor.codeActionsOnSave": {
+    "source.fixAll": "explicit",
+    "source.organizeImports": "explicit",
+    "source.sortMembers": "explicit"
+  }
+}
--- a/apps/mobile/README.md
+++ b/apps/mobile/README.md
@ -0,0 +1,50 @@
+# Welcome to your Expo app 👋
+
+This is an [Expo](https://expo.dev) project created with [`create-expo-app`](https://www.npmjs.com/package/create-expo-app).
+
+## Get started
+
+1. Install dependencies
+
+   ```bash
+   npm install
+   ```
+
+2. Start the app
+
+   ```bash
+   npx expo start
+   ```
+
+In the output, you'll find options to open the app in a
+
+- [development build](https://docs.expo.dev/develop/development-builds/introduction/)
+- [Android emulator](https://docs.expo.dev/workflow/android-studio-emulator/)
+- [iOS simulator](https://docs.expo.dev/workflow/ios-simulator/)
+- [Expo Go](https://expo.dev/go), a limited sandbox for trying out app development with Expo
+
+You can start developing by editing the files inside the **app** directory. This project uses [file-based routing](https://docs.expo.dev/router/introduction).
+
+## Get a fresh project
+
+When you're ready, run:
+
+```bash
+npm run reset-project
+```
+
+This command will move the starter code to the **app-example** directory and create a blank **app** directory where you can start developing.
+
+## Learn more
+
+To learn more about developing your project with Expo, look at the following resources:
+
+- [Expo documentation](https://docs.expo.dev/): Learn fundamentals, or go into advanced topics with our [guides](https://docs.expo.dev/guides).
+- [Learn Expo tutorial](https://docs.expo.dev/tutorial/introduction/): Follow a step-by-step tutorial where you'll create a project that runs on Android, iOS, and the web.
+
+## Join the community
+
+Join our community of developers creating universal apps.
+
+- [Expo on GitHub](https://github.com/expo/expo): View our open source platform and contribute.
+- [Discord community](https://chat.expo.dev): Chat with Expo users and ask questions.
--- a/apps/mobile/app.json
+++ b/apps/mobile/app.json
@ -0,0 +1,48 @@
+{
+  "expo": {
+    "name": "Multica",
+    "slug": "multica-mobile",
+    "version": "1.0.0",
+    "orientation": "portrait",
+    "icon": "./assets/images/icon.png",
+    "scheme": "mobile",
+    "userInterfaceStyle": "automatic",
+    "newArchEnabled": true,
+    "ios": {
+      "supportsTablet": true
+    },
+    "android": {
+      "adaptiveIcon": {
+        "backgroundColor": "#E6F4FE",
+        "foregroundImage": "./assets/images/android-icon-foreground.png",
+        "backgroundImage": "./assets/images/android-icon-background.png",
+        "monochromeImage": "./assets/images/android-icon-monochrome.png"
+      },
+      "edgeToEdgeEnabled": true,
+      "predictiveBackGestureEnabled": false
+    },
+    "web": {
+      "output": "static",
+      "favicon": "./assets/images/favicon.png"
+    },
+    "plugins": [
+      "expo-router",
+      [
+        "expo-splash-screen",
+        {
+          "image": "./assets/images/splash-icon.png",
+          "imageWidth": 200,
+          "resizeMode": "contain",
+          "backgroundColor": "#ffffff",
+          "dark": {
+            "backgroundColor": "#000000"
+          }
+        }
+      ]
+    ],
+    "experiments": {
+      "typedRoutes": true,
+      "reactCompiler": true
+    }
+  }
+}
--- a/apps/mobile/app/_layout.tsx
+++ b/apps/mobile/app/_layout.tsx
@ -0,0 +1,21 @@
+import "../global.css";
+import { ThemeProvider } from "@react-navigation/native";
+import { PortalHost } from "@rn-primitives/portal";
+import { Stack } from "expo-router";
+import { StatusBar } from "expo-status-bar";
+import { useColorScheme } from "nativewind";
+import "react-native-reanimated";
+
+import { NAV_THEME } from "@/lib/theme";
+
+export default function RootLayout() {
+  const { colorScheme } = useColorScheme();
+
+  return (
+    <ThemeProvider value={NAV_THEME[colorScheme ?? "light"]}>
+      <StatusBar style={colorScheme === "dark" ? "light" : "dark"} />
+      <Stack screenOptions={{ headerShown: false }} />
+      <PortalHost />
+    </ThemeProvider>
+  );
+}
--- a/apps/mobile/app/index.tsx
+++ b/apps/mobile/app/index.tsx
@ -0,0 +1,167 @@
+import { useState, useRef, useCallback } from "react";
+import {
+  View,
+  ScrollView,
+  KeyboardAvoidingView,
+  Platform,
+  TextInput,
+  Pressable,
+  LayoutAnimation,
+  UIManager,
+} from "react-native";
+import { SafeAreaView } from "react-native-safe-area-context";
+import { Text } from "@/components/ui/text";
+import { HugeiconsIcon } from "@hugeicons/react-native";
+import { ArrowUp01Icon } from "@hugeicons/core-free-icons";
+
+// Enable LayoutAnimation on Android
+if (Platform.OS === "android" && UIManager.setLayoutAnimationEnabledExperimental) {
+  UIManager.setLayoutAnimationEnabledExperimental(true);
+}
+
+const INPUT_MAX_HEIGHT = 120;
+const SINGLE_LINE_HEIGHT = 20; // approximate single line content height
+
+const MOCK_MESSAGES = [
+  { id: "1", role: "user", content: "Hello, can you help me with a task?" },
+  {
+    id: "2",
+    role: "assistant",
+    content:
+      "Of course! I'd be happy to help. What would you like me to do?",
+  },
+  { id: "3", role: "user", content: "Explain how WebSockets work." },
+  {
+    id: "4",
+    role: "assistant",
+    content:
+      "WebSockets provide full-duplex communication channels over a single TCP connection. Unlike HTTP, which is request-response based, WebSockets allow both the client and server to send messages independently at any time.\n\nThe connection starts as a standard HTTP request, then upgrades to a persistent WebSocket connection via a handshake.",
+  },
+];
+
+export default function Index() {
+  const [input, setInput] = useState("");
+  const [messages, setMessages] = useState(MOCK_MESSAGES);
+  const [contentHeight, setContentHeight] = useState(SINGLE_LINE_HEIGHT);
+  const scrollRef = useRef<ScrollView>(null);
+
+  const isMultiline = contentHeight > SINGLE_LINE_HEIGHT + 4;
+
+  const handleContentSizeChange = useCallback(
+    (e: { nativeEvent: { contentSize: { height: number } } }) => {
+      const newHeight = e.nativeEvent.contentSize.height;
+      if (newHeight !== contentHeight) {
+        LayoutAnimation.configureNext(
+          LayoutAnimation.create(150, "easeInEaseOut", "opacity")
+        );
+        setContentHeight(newHeight);
+      }
+    },
+    [contentHeight]
+  );
+
+  function handleSend() {
+    const trimmed = input.trim();
+    if (!trimmed) return;
+
+    setMessages((prev) => [
+      ...prev,
+      { id: String(Date.now()), role: "user", content: trimmed },
+    ]);
+    setInput("");
+    LayoutAnimation.configureNext(
+      LayoutAnimation.create(150, "easeInEaseOut", "opacity")
+    );
+    setContentHeight(SINGLE_LINE_HEIGHT);
+    setTimeout(() => scrollRef.current?.scrollToEnd({ animated: true }), 100);
+  }
+
+  const canSend = input.trim().length > 0;
+
+  return (
+    <SafeAreaView className="flex-1 bg-background">
+      <KeyboardAvoidingView
+        className="flex-1"
+        behavior={Platform.OS === "ios" ? "padding" : "height"}
+      >
+        {/* Header */}
+        <View className="px-4 py-3">
+          <Text className="text-lg font-semibold text-foreground">Multica</Text>
+          <Text className="text-xs text-muted-foreground">Agent connected</Text>
+        </View>
+
+        {/* Messages */}
+        <ScrollView
+          ref={scrollRef}
+          className="flex-1"
+          contentContainerClassName="px-4 py-2 gap-5"
+          keyboardShouldPersistTaps="handled"
+        >
+          {messages.map((msg) =>
+            msg.role === "user" ? (
+              <View key={msg.id} className="flex-row justify-end">
+                <View className="max-w-[80%] rounded-2xl rounded-br-sm bg-muted px-4 py-2.5">
+                  <Text className="text-[15px] leading-[22px] text-foreground">
+                    {msg.content}
+                  </Text>
+                </View>
+              </View>
+            ) : (
+              <View key={msg.id}>
+                <Text className="text-[15px] leading-[22px] text-foreground">
+                  {msg.content}
+                </Text>
+              </View>
+            )
+          )}
+        </ScrollView>
+
+        {/* Input bar */}
+        <View className="px-3 pb-1 pt-2">
+          <View
+            className={`flex-row border border-border bg-card pl-4 pr-1.5 py-1.5 ${
+              isMultiline ? "items-end rounded-2xl" : "items-center rounded-full"
+            }`}
+          >
+            <TextInput
+              className="flex-1 border-0 bg-transparent text-[15px] leading-5 text-foreground"
+              placeholder="Type a message..."
+              placeholderTextColor="hsl(240.1, 4.4%, 46.3%)"
+              value={input}
+              onChangeText={setInput}
+              onSubmitEditing={handleSend}
+              onContentSizeChange={handleContentSizeChange}
+              multiline
+              scrollEnabled={contentHeight >= INPUT_MAX_HEIGHT}
+              textAlignVertical="top"
+              selectionColor="hsl(243.5, 75.2%, 58.5%)"
+              underlineColorAndroid="transparent"
+              style={{
+                maxHeight: INPUT_MAX_HEIGHT,
+                paddingTop: 0,
+                paddingBottom: 0,
+                // @ts-ignore web-only: remove browser default outline/border
+                outline: "none",
+                borderWidth: 0,
+                boxShadow: "none",
+              }}
+            />
+            <Pressable
+              onPress={handleSend}
+              disabled={!canSend}
+              className="ml-1.5 h-8 w-8 items-center justify-center rounded-full bg-primary"
+              style={{ opacity: canSend ? 1 : 0.5 }}
+            >
+              <HugeiconsIcon
+                icon={ArrowUp01Icon}
+                size={18}
+                color="hsl(225, 100%, 96.4%)"
+                strokeWidth={2.5}
+              />
+            </Pressable>
+          </View>
+        </View>
+      </KeyboardAvoidingView>
+    </SafeAreaView>
+  );
+}
--- a/apps/mobile/assets/images/android-icon-background.png
+++ b/apps/mobile/assets/images/android-icon-background.png
--- a/apps/mobile/assets/images/android-icon-foreground.png
+++ b/apps/mobile/assets/images/android-icon-foreground.png
--- a/apps/mobile/assets/images/android-icon-monochrome.png
+++ b/apps/mobile/assets/images/android-icon-monochrome.png
--- a/apps/mobile/assets/images/favicon.png
+++ b/apps/mobile/assets/images/favicon.png
--- a/apps/mobile/assets/images/icon.png
+++ b/apps/mobile/assets/images/icon.png
--- a/apps/mobile/assets/images/partial-react-logo.png
+++ b/apps/mobile/assets/images/partial-react-logo.png
--- a/apps/mobile/assets/images/react-logo.png
+++ b/apps/mobile/assets/images/react-logo.png
--- a/apps/mobile/assets/images/react-logo@2x.png
+++ b/apps/mobile/assets/images/react-logo@2x.png
--- a/apps/mobile/assets/images/react-logo@3x.png
+++ b/apps/mobile/assets/images/react-logo@3x.png
--- a/apps/mobile/assets/images/splash-icon.png
+++ b/apps/mobile/assets/images/splash-icon.png
--- a/apps/mobile/babel.config.js
+++ b/apps/mobile/babel.config.js
@ -0,0 +1,9 @@
+module.exports = function (api) {
+  api.cache(true);
+  return {
+    presets: [
+      ["babel-preset-expo", { jsxImportSource: "nativewind" }],
+      "nativewind/babel",
+    ],
+  };
+};
--- a/apps/mobile/components.json
+++ b/apps/mobile/components.json
@ -0,0 +1,19 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "tailwind.config.js",
+    "css": "global.css",
+    "baseColor": "zinc",
+    "cssVariables": true
+  },
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  }
+}
--- a/apps/mobile/components/ui/button.tsx
+++ b/apps/mobile/components/ui/button.tsx
@ -0,0 +1,108 @@
+import { TextClassContext } from '@/components/ui/text';
+import { cn } from '@/lib/utils';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { Platform, Pressable } from 'react-native';
+
+const buttonVariants = cva(
+  cn(
+    'group shrink-0 flex-row items-center justify-center gap-2 rounded-md shadow-none',
+    Platform.select({
+      web: "focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive whitespace-nowrap outline-none transition-all focus-visible:ring-[3px] disabled:pointer-events-none [&_svg:not([class*='size-'])]:size-4 [&_svg]:pointer-events-none [&_svg]:shrink-0",
+    })
+  ),
+  {
+    variants: {
+      variant: {
+        default: cn(
+          'bg-primary active:bg-primary/90 shadow-sm shadow-black/5',
+          Platform.select({ web: 'hover:bg-primary/90' })
+        ),
+        destructive: cn(
+          'bg-destructive active:bg-destructive/90 dark:bg-destructive/60 shadow-sm shadow-black/5',
+          Platform.select({
+            web: 'hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40',
+          })
+        ),
+        outline: cn(
+          'border-border bg-background active:bg-accent dark:bg-input/30 dark:border-input dark:active:bg-input/50 border shadow-sm shadow-black/5',
+          Platform.select({
+            web: 'hover:bg-accent dark:hover:bg-input/50',
+          })
+        ),
+        secondary: cn(
+          'bg-secondary active:bg-secondary/80 shadow-sm shadow-black/5',
+          Platform.select({ web: 'hover:bg-secondary/80' })
+        ),
+        ghost: cn(
+          'active:bg-accent dark:active:bg-accent/50',
+          Platform.select({ web: 'hover:bg-accent dark:hover:bg-accent/50' })
+        ),
+        link: '',
+      },
+      size: {
+        default: cn('h-10 px-4 py-2 sm:h-9', Platform.select({ web: 'has-[>svg]:px-3' })),
+        sm: cn('h-9 gap-1.5 rounded-md px-3 sm:h-8', Platform.select({ web: 'has-[>svg]:px-2.5' })),
+        lg: cn('h-11 rounded-md px-6 sm:h-10', Platform.select({ web: 'has-[>svg]:px-4' })),
+        icon: 'h-10 w-10 sm:h-9 sm:w-9',
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+      size: 'default',
+    },
+  }
+);
+
+const buttonTextVariants = cva(
+  cn(
+    'text-foreground text-sm font-medium',
+    Platform.select({ web: 'pointer-events-none transition-colors' })
+  ),
+  {
+    variants: {
+      variant: {
+        default: 'text-primary-foreground',
+        destructive: 'text-white',
+        outline: cn(
+          'group-active:text-accent-foreground',
+          Platform.select({ web: 'group-hover:text-accent-foreground' })
+        ),
+        secondary: 'text-secondary-foreground',
+        ghost: 'group-active:text-accent-foreground',
+        link: cn(
+          'text-primary group-active:underline',
+          Platform.select({ web: 'underline-offset-4 hover:underline group-hover:underline' })
+        ),
+      },
+      size: {
+        default: '',
+        sm: '',
+        lg: '',
+        icon: '',
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+      size: 'default',
+    },
+  }
+);
+
+type ButtonProps = React.ComponentProps<typeof Pressable> &
+  React.RefAttributes<typeof Pressable> &
+  VariantProps<typeof buttonVariants>;
+
+function Button({ className, variant, size, ...props }: ButtonProps) {
+  return (
+    <TextClassContext.Provider value={buttonTextVariants({ variant, size })}>
+      <Pressable
+        className={cn(props.disabled && 'opacity-50', buttonVariants({ variant, size }), className)}
+        role="button"
+        {...props}
+      />
+    </TextClassContext.Provider>
+  );
+}
+
+export { Button, buttonTextVariants, buttonVariants };
+export type { ButtonProps };
--- a/apps/mobile/components/ui/card.tsx
+++ b/apps/mobile/components/ui/card.tsx
@ -0,0 +1,52 @@
+import { Text, TextClassContext } from '@/components/ui/text';
+import { cn } from '@/lib/utils';
+import { View, type ViewProps } from 'react-native';
+
+function Card({ className, ...props }: ViewProps & React.RefAttributes<View>) {
+  return (
+    <TextClassContext.Provider value="text-card-foreground">
+      <View
+        className={cn(
+          'bg-card border-border flex flex-col gap-6 rounded-xl border py-6 shadow-sm shadow-black/5',
+          className
+        )}
+        {...props}
+      />
+    </TextClassContext.Provider>
+  );
+}
+
+function CardHeader({ className, ...props }: ViewProps & React.RefAttributes<View>) {
+  return <View className={cn('flex flex-col gap-1.5 px-6', className)} {...props} />;
+}
+
+function CardTitle({
+  className,
+  ...props
+}: React.ComponentProps<typeof Text> & React.RefAttributes<Text>) {
+  return (
+    <Text
+      role="heading"
+      aria-level={3}
+      className={cn('font-semibold leading-none', className)}
+      {...props}
+    />
+  );
+}
+
+function CardDescription({
+  className,
+  ...props
+}: React.ComponentProps<typeof Text> & React.RefAttributes<Text>) {
+  return <Text className={cn('text-muted-foreground text-sm', className)} {...props} />;
+}
+
+function CardContent({ className, ...props }: ViewProps & React.RefAttributes<View>) {
+  return <View className={cn('px-6', className)} {...props} />;
+}
+
+function CardFooter({ className, ...props }: ViewProps & React.RefAttributes<View>) {
+  return <View className={cn('flex flex-row items-center px-6', className)} {...props} />;
+}
+
+export { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle };
--- a/apps/mobile/components/ui/collapsible.tsx
+++ b/apps/mobile/components/ui/collapsible.tsx
@ -0,0 +1,45 @@
+import { PropsWithChildren, useState } from 'react';
+import { StyleSheet, TouchableOpacity } from 'react-native';
+
+import { ThemedText } from '@/components/themed-text';
+import { ThemedView } from '@/components/themed-view';
+import { IconSymbol } from '@/components/ui/icon-symbol';
+import { Colors } from '@/constants/theme';
+import { useColorScheme } from '@/hooks/use-color-scheme';
+
+export function Collapsible({ children, title }: PropsWithChildren & { title: string }) {
+  const [isOpen, setIsOpen] = useState(false);
+  const theme = useColorScheme() ?? 'light';
+
+  return (
+    <ThemedView>
+      <TouchableOpacity
+        style={styles.heading}
+        onPress={() => setIsOpen((value) => !value)}
+        activeOpacity={0.8}>
+        <IconSymbol
+          name="chevron.right"
+          size={18}
+          weight="medium"
+          color={theme === 'light' ? Colors.light.icon : Colors.dark.icon}
+          style={{ transform: [{ rotate: isOpen ? '90deg' : '0deg' }] }}
+        />
+
+        <ThemedText type="defaultSemiBold">{title}</ThemedText>
+      </TouchableOpacity>
+      {isOpen && <ThemedView style={styles.content}>{children}</ThemedView>}
+    </ThemedView>
+  );
+}
+
+const styles = StyleSheet.create({
+  heading: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: 6,
+  },
+  content: {
+    marginTop: 6,
+    marginLeft: 24,
+  },
+});
--- a/apps/mobile/components/ui/icon-symbol.ios.tsx
+++ b/apps/mobile/components/ui/icon-symbol.ios.tsx
@ -0,0 +1,32 @@
+import { SymbolView, SymbolViewProps, SymbolWeight } from 'expo-symbols';
+import { StyleProp, ViewStyle } from 'react-native';
+
+export function IconSymbol({
+  name,
+  size = 24,
+  color,
+  style,
+  weight = 'regular',
+}: {
+  name: SymbolViewProps['name'];
+  size?: number;
+  color: string;
+  style?: StyleProp<ViewStyle>;
+  weight?: SymbolWeight;
+}) {
+  return (
+    <SymbolView
+      weight={weight}
+      tintColor={color}
+      resizeMode="scaleAspectFit"
+      name={name}
+      style={[
+        {
+          width: size,
+          height: size,
+        },
+        style,
+      ]}
+    />
+  );
+}
--- a/apps/mobile/components/ui/icon-symbol.tsx
+++ b/apps/mobile/components/ui/icon-symbol.tsx
@ -0,0 +1,41 @@
+// Fallback for using MaterialIcons on Android and web.
+
+import MaterialIcons from '@expo/vector-icons/MaterialIcons';
+import { SymbolWeight, SymbolViewProps } from 'expo-symbols';
+import { ComponentProps } from 'react';
+import { OpaqueColorValue, type StyleProp, type TextStyle } from 'react-native';
+
+type IconMapping = Record<SymbolViewProps['name'], ComponentProps<typeof MaterialIcons>['name']>;
+type IconSymbolName = keyof typeof MAPPING;
+
+/**
+ * Add your SF Symbols to Material Icons mappings here.
+ * - see Material Icons in the [Icons Directory](https://icons.expo.fyi).
+ * - see SF Symbols in the [SF Symbols](https://developer.apple.com/sf-symbols/) app.
+ */
+const MAPPING = {
+  'house.fill': 'home',
+  'paperplane.fill': 'send',
+  'chevron.left.forwardslash.chevron.right': 'code',
+  'chevron.right': 'chevron-right',
+} as IconMapping;
+
+/**
+ * An icon component that uses native SF Symbols on iOS, and Material Icons on Android and web.
+ * This ensures a consistent look across platforms, and optimal resource usage.
+ * Icon `name`s are based on SF Symbols and require manual mapping to Material Icons.
+ */
+export function IconSymbol({
+  name,
+  size = 24,
+  color,
+  style,
+}: {
+  name: IconSymbolName;
+  size?: number;
+  color: string | OpaqueColorValue;
+  style?: StyleProp<TextStyle>;
+  weight?: SymbolWeight;
+}) {
+  return <MaterialIcons color={color} size={size} name={MAPPING[name]} style={style} />;
+}
--- a/apps/mobile/components/ui/input.tsx
+++ b/apps/mobile/components/ui/input.tsx
@ -0,0 +1,29 @@
+import { cn } from '@/lib/utils';
+import { Platform, TextInput, type TextInputProps } from 'react-native';
+
+function Input({ className, ...props }: TextInputProps & React.RefAttributes<TextInput>) {
+  return (
+    <TextInput
+      className={cn(
+        'dark:bg-input/30 border-input bg-background text-foreground flex h-10 w-full min-w-0 flex-row items-center rounded-md border px-3 py-1 text-base leading-5 shadow-sm shadow-black/5 sm:h-9',
+        props.editable === false &&
+          cn(
+            'opacity-50',
+            Platform.select({ web: 'disabled:pointer-events-none disabled:cursor-not-allowed' })
+          ),
+        Platform.select({
+          web: cn(
+            'placeholder:text-muted-foreground selection:bg-primary selection:text-primary-foreground outline-none transition-[color,box-shadow] md:text-sm',
+            'focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px]',
+            'aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive'
+          ),
+          native: 'placeholder:text-muted-foreground/50',
+        }),
+        className
+      )}
+      {...props}
+    />
+  );
+}
+
+export { Input };
--- a/apps/mobile/components/ui/text.tsx
+++ b/apps/mobile/components/ui/text.tsx
@ -0,0 +1,89 @@
+import { cn } from '@/lib/utils';
+import * as Slot from '@rn-primitives/slot';
+import { cva, type VariantProps } from 'class-variance-authority';
+import * as React from 'react';
+import { Platform, Text as RNText, type Role } from 'react-native';
+
+const textVariants = cva(
+  cn(
+    'text-foreground text-base',
+    Platform.select({
+      web: 'select-text',
+    })
+  ),
+  {
+    variants: {
+      variant: {
+        default: '',
+        h1: cn(
+          'text-center text-4xl font-extrabold tracking-tight',
+          Platform.select({ web: 'scroll-m-20 text-balance' })
+        ),
+        h2: cn(
+          'border-border border-b pb-2 text-3xl font-semibold tracking-tight',
+          Platform.select({ web: 'scroll-m-20 first:mt-0' })
+        ),
+        h3: cn('text-2xl font-semibold tracking-tight', Platform.select({ web: 'scroll-m-20' })),
+        h4: cn('text-xl font-semibold tracking-tight', Platform.select({ web: 'scroll-m-20' })),
+        p: 'mt-3 leading-7 sm:mt-6',
+        blockquote: 'mt-4 border-l-2 pl-3 italic sm:mt-6 sm:pl-6',
+        code: cn(
+          'bg-muted relative rounded px-[0.3rem] py-[0.2rem] font-mono text-sm font-semibold'
+        ),
+        lead: 'text-muted-foreground text-xl',
+        large: 'text-lg font-semibold',
+        small: 'text-sm font-medium leading-none',
+        muted: 'text-muted-foreground text-sm',
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+    },
+  }
+);
+
+type TextVariantProps = VariantProps<typeof textVariants>;
+
+type TextVariant = NonNullable<TextVariantProps['variant']>;
+
+const ROLE: Partial<Record<TextVariant, Role>> = {
+  h1: 'heading',
+  h2: 'heading',
+  h3: 'heading',
+  h4: 'heading',
+  blockquote: Platform.select({ web: 'blockquote' as Role }),
+  code: Platform.select({ web: 'code' as Role }),
+};
+
+const ARIA_LEVEL: Partial<Record<TextVariant, string>> = {
+  h1: '1',
+  h2: '2',
+  h3: '3',
+  h4: '4',
+};
+
+const TextClassContext = React.createContext<string | undefined>(undefined);
+
+function Text({
+  className,
+  asChild = false,
+  variant = 'default',
+  ...props
+}: React.ComponentProps<typeof RNText> &
+  TextVariantProps &
+  React.RefAttributes<RNText> & {
+    asChild?: boolean;
+  }) {
+  const textClass = React.useContext(TextClassContext);
+  const Component = asChild ? Slot.Text : RNText;
+  return (
+    <Component
+      className={cn(textVariants({ variant }), textClass, className)}
+      role={variant ? ROLE[variant] : undefined}
+      aria-level={variant ? ARIA_LEVEL[variant] : undefined}
+      {...props}
+    />
+  );
+}
+
+export { Text, TextClassContext };
--- a/apps/mobile/eslint.config.js
+++ b/apps/mobile/eslint.config.js
@ -0,0 +1,10 @@
+// https://docs.expo.dev/guides/using-eslint/
+const { defineConfig } = require('eslint/config');
+const expoConfig = require('eslint-config-expo/flat');
+
+module.exports = defineConfig([
+  expoConfig,
+  {
+    ignores: ['dist/*'],
+  },
+]);
--- a/apps/mobile/global.css
+++ b/apps/mobile/global.css
@ -0,0 +1,61 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+  :root {
+    --background: 0 0% 100%;
+    --foreground: 240.1 11.2% 4%;
+    --card: 0 0% 100%;
+    --card-foreground: 240.1 11.2% 4%;
+    --popover: 0 0% 100%;
+    --popover-foreground: 240.1 11.2% 4%;
+    --primary: 243.5 75.2% 58.5%;
+    --primary-foreground: 225 100% 96.4%;
+    --secondary: 240 3.5% 95.8%;
+    --secondary-foreground: 240 6% 10%;
+    --muted: 240 3.5% 95.8%;
+    --muted-foreground: 240.1 4.4% 46.3%;
+    --accent: 240 3.5% 95.8%;
+    --accent-foreground: 240 6% 10%;
+    --destructive: 357.2 100% 45.3%;
+    --destructive-foreground: 0 0% 98%;
+    --border: 240 5.9% 90%;
+    --input: 240 5.9% 90%;
+    --ring: 240.1 5.7% 64.3%;
+    --radius: 0.625rem;
+    --chart-1: 229.8 91.2% 82.1%;
+    --chart-2: 234.6 90.8% 74.1%;
+    --chart-3: 238.2 82.8% 66.8%;
+    --chart-4: 243.5 75.2% 58.5%;
+    --chart-5: 243.8 56.7% 50.9%;
+  }
+
+  .dark:root {
+    --background: 240.1 11.2% 4%;
+    --foreground: 180 0% 98%;
+    --card: 240 6% 10%;
+    --card-foreground: 180 0% 98%;
+    --popover: 240 6% 10%;
+    --popover-foreground: 180 0% 98%;
+    --primary: 238.2 82.8% 66.8%;
+    --primary-foreground: 225 100% 96.4%;
+    --secondary: 240 4% 15.9%;
+    --secondary-foreground: 180 0% 98%;
+    --muted: 240 4% 15.9%;
+    --muted-foreground: 240.1 5.7% 64.3%;
+    --accent: 240 4% 15.9%;
+    --accent-foreground: 180 0% 98%;
+    --destructive: 358.7 100% 69.6%;
+    --destructive-foreground: 0 0% 98%;
+    --border: 240 5% 11%;
+    --input: 240 4% 15.5%;
+    --ring: 240.1 4.4% 46.3%;
+    --radius: 0.625rem;
+    --chart-1: 229.8 91.2% 82.1%;
+    --chart-2: 234.6 90.8% 74.1%;
+    --chart-3: 238.2 82.8% 66.8%;
+    --chart-4: 243.5 75.2% 58.5%;
+    --chart-5: 243.8 56.7% 50.9%;
+  }
+}
--- a/apps/mobile/lib/theme.ts
+++ b/apps/mobile/lib/theme.ts
@ -0,0 +1,71 @@
+import { DarkTheme, DefaultTheme, type Theme } from "@react-navigation/native";
+
+export const THEME = {
+  light: {
+    background: "hsl(0, 0%, 100%)",
+    foreground: "hsl(240.1, 11.2%, 4%)",
+    card: "hsl(0, 0%, 100%)",
+    cardForeground: "hsl(240.1, 11.2%, 4%)",
+    popover: "hsl(0, 0%, 100%)",
+    popoverForeground: "hsl(240.1, 11.2%, 4%)",
+    primary: "hsl(243.5, 75.2%, 58.5%)",
+    primaryForeground: "hsl(225, 100%, 96.4%)",
+    secondary: "hsl(240, 3.5%, 95.8%)",
+    secondaryForeground: "hsl(240, 6%, 10%)",
+    muted: "hsl(240, 3.5%, 95.8%)",
+    mutedForeground: "hsl(240.1, 4.4%, 46.3%)",
+    accent: "hsl(240, 3.5%, 95.8%)",
+    accentForeground: "hsl(240, 6%, 10%)",
+    destructive: "hsl(357.2, 100%, 45.3%)",
+    border: "hsl(240, 5.9%, 90%)",
+    input: "hsl(240, 5.9%, 90%)",
+    ring: "hsl(240.1, 5.7%, 64.3%)",
+    radius: "0.625rem",
+  },
+  dark: {
+    background: "hsl(240.1, 11.2%, 4%)",
+    foreground: "hsl(180, 0%, 98%)",
+    card: "hsl(240, 6%, 10%)",
+    cardForeground: "hsl(180, 0%, 98%)",
+    popover: "hsl(240, 6%, 10%)",
+    popoverForeground: "hsl(180, 0%, 98%)",
+    primary: "hsl(238.2, 82.8%, 66.8%)",
+    primaryForeground: "hsl(225, 100%, 96.4%)",
+    secondary: "hsl(240, 4%, 15.9%)",
+    secondaryForeground: "hsl(180, 0%, 98%)",
+    muted: "hsl(240, 4%, 15.9%)",
+    mutedForeground: "hsl(240.1, 5.7%, 64.3%)",
+    accent: "hsl(240, 4%, 15.9%)",
+    accentForeground: "hsl(180, 0%, 98%)",
+    destructive: "hsl(358.7, 100%, 69.6%)",
+    border: "hsl(240, 5%, 11%)",
+    input: "hsl(240, 4%, 15.5%)",
+    ring: "hsl(240.1, 4.4%, 46.3%)",
+    radius: "0.625rem",
+  },
+};
+
+export const NAV_THEME: Record<"light" | "dark", Theme> = {
+  light: {
+    ...DefaultTheme,
+    colors: {
+      background: THEME.light.background,
+      border: THEME.light.border,
+      card: THEME.light.card,
+      notification: THEME.light.destructive,
+      primary: THEME.light.primary,
+      text: THEME.light.foreground,
+    },
+  },
+  dark: {
+    ...DarkTheme,
+    colors: {
+      background: THEME.dark.background,
+      border: THEME.dark.border,
+      card: THEME.dark.card,
+      notification: THEME.dark.destructive,
+      primary: THEME.dark.primary,
+      text: THEME.dark.foreground,
+    },
+  },
+};
--- a/apps/mobile/lib/utils.ts
+++ b/apps/mobile/lib/utils.ts
@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
--- a/apps/mobile/metro.config.js
+++ b/apps/mobile/metro.config.js
@ -0,0 +1,6 @@
+const { getDefaultConfig } = require("expo/metro-config");
+const { withNativeWind } = require("nativewind/metro");
+
+const config = getDefaultConfig(__dirname);
+
+module.exports = withNativeWind(config, { input: "./global.css", inlineRem: 16 });
--- a/apps/mobile/nativewind-env.d.ts
+++ b/apps/mobile/nativewind-env.d.ts
@ -0,0 +1 @@
+/// <reference types="nativewind/types" />
--- a/apps/mobile/package.json
+++ b/apps/mobile/package.json
@ -0,0 +1,60 @@
+{
+  "name": "@multica/mobile",
+  "main": "expo-router/entry",
+  "version": "1.0.0",
+  "scripts": {
+    "start": "expo start",
+    "reset-project": "node ./scripts/reset-project.js",
+    "android": "expo start --android",
+    "ios": "expo start --ios",
+    "web": "expo start --web",
+    "lint": "expo lint"
+  },
+  "dependencies": {
+    "@expo/vector-icons": "^15.0.3",
+    "@hugeicons/core-free-icons": "^3.1.1",
+    "@hugeicons/react-native": "^1.0.11",
+    "@react-navigation/bottom-tabs": "^7.4.0",
+    "@react-navigation/elements": "^2.6.3",
+    "@react-navigation/native": "^7.1.8",
+    "@rn-primitives/portal": "^1.3.0",
+    "@rn-primitives/slot": "^1.2.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "expo": "~54.0.33",
+    "expo-constants": "~18.0.13",
+    "expo-font": "~14.0.11",
+    "expo-haptics": "~15.0.8",
+    "expo-image": "~3.0.11",
+    "expo-linking": "~8.0.11",
+    "expo-router": "~6.0.23",
+    "expo-splash-screen": "~31.0.13",
+    "expo-status-bar": "~3.0.9",
+    "expo-symbols": "~1.0.8",
+    "expo-system-ui": "~6.0.9",
+    "expo-web-browser": "~15.0.10",
+    "lucide-react-native": "^0.563.0",
+    "nativewind": "^4.2.1",
+    "react": "19.1.0",
+    "react-dom": "19.1.0",
+    "react-native": "0.81.5",
+    "react-native-css-interop": "^0.2.1",
+    "react-native-gesture-handler": "~2.28.0",
+    "react-native-reanimated": "~4.1.1",
+    "react-native-safe-area-context": "~5.6.0",
+    "react-native-screens": "~4.16.0",
+    "react-native-svg": "^15.15.1",
+    "react-native-web": "~0.21.0",
+    "react-native-worklets": "0.5.1",
+    "tailwind-merge": "^3.4.0",
+    "tailwindcss-animate": "^1.0.7"
+  },
+  "devDependencies": {
+    "@types/react": "~19.1.0",
+    "eslint": "^9.25.0",
+    "eslint-config-expo": "~10.0.0",
+    "tailwindcss": "3.4.17",
+    "typescript": "~5.9.2"
+  },
+  "private": true
+}
--- a/apps/mobile/scripts/reset-project.js
+++ b/apps/mobile/scripts/reset-project.js
@ -0,0 +1,112 @@
+#!/usr/bin/env node
+
+/**
+ * This script is used to reset the project to a blank state.
+ * It deletes or moves the /app, /components, /hooks, /scripts, and /constants directories to /app-example based on user input and creates a new /app directory with an index.tsx and _layout.tsx file.
+ * You can remove the `reset-project` script from package.json and safely delete this file after running it.
+ */
+
+const fs = require("fs");
+const path = require("path");
+const readline = require("readline");
+
+const root = process.cwd();
+const oldDirs = ["app", "components", "hooks", "constants", "scripts"];
+const exampleDir = "app-example";
+const newAppDir = "app";
+const exampleDirPath = path.join(root, exampleDir);
+
+const indexContent = `import { Text, View } from "react-native";
+
+export default function Index() {
+  return (
+    <View
+      style={{
+        flex: 1,
+        justifyContent: "center",
+        alignItems: "center",
+      }}
+    >
+      <Text>Edit app/index.tsx to edit this screen.</Text>
+    </View>
+  );
+}
+`;
+
+const layoutContent = `import { Stack } from "expo-router";
+
+export default function RootLayout() {
+  return <Stack />;
+}
+`;
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout,
+});
+
+const moveDirectories = async (userInput) => {
+  try {
+    if (userInput === "y") {
+      // Create the app-example directory
+      await fs.promises.mkdir(exampleDirPath, { recursive: true });
+      console.log(`📁 /${exampleDir} directory created.`);
+    }
+
+    // Move old directories to new app-example directory or delete them
+    for (const dir of oldDirs) {
+      const oldDirPath = path.join(root, dir);
+      if (fs.existsSync(oldDirPath)) {
+        if (userInput === "y") {
+          const newDirPath = path.join(root, exampleDir, dir);
+          await fs.promises.rename(oldDirPath, newDirPath);
+          console.log(`➡️ /${dir} moved to /${exampleDir}/${dir}.`);
+        } else {
+          await fs.promises.rm(oldDirPath, { recursive: true, force: true });
+          console.log(`❌ /${dir} deleted.`);
+        }
+      } else {
+        console.log(`➡️ /${dir} does not exist, skipping.`);
+      }
+    }
+
+    // Create new /app directory
+    const newAppDirPath = path.join(root, newAppDir);
+    await fs.promises.mkdir(newAppDirPath, { recursive: true });
+    console.log("\n📁 New /app directory created.");
+
+    // Create index.tsx
+    const indexPath = path.join(newAppDirPath, "index.tsx");
+    await fs.promises.writeFile(indexPath, indexContent);
+    console.log("📄 app/index.tsx created.");
+
+    // Create _layout.tsx
+    const layoutPath = path.join(newAppDirPath, "_layout.tsx");
+    await fs.promises.writeFile(layoutPath, layoutContent);
+    console.log("📄 app/_layout.tsx created.");
+
+    console.log("\n✅ Project reset complete. Next steps:");
+    console.log(
+      `1. Run \`npx expo start\` to start a development server.\n2. Edit app/index.tsx to edit the main screen.${
+        userInput === "y"
+          ? `\n3. Delete the /${exampleDir} directory when you're done referencing it.`
+          : ""
+      }`
+    );
+  } catch (error) {
+    console.error(`❌ Error during script execution: ${error.message}`);
+  }
+};
+
+rl.question(
+  "Do you want to move existing files to /app-example instead of deleting them? (Y/n): ",
+  (answer) => {
+    const userInput = answer.trim().toLowerCase() || "y";
+    if (userInput === "y" || userInput === "n") {
+      moveDirectories(userInput).finally(() => rl.close());
+    } else {
+      console.log("❌ Invalid input. Please enter 'Y' or 'N'.");
+      rl.close();
+    }
+  }
+);
--- a/apps/mobile/tailwind.config.js
+++ b/apps/mobile/tailwind.config.js
@ -0,0 +1,59 @@
+const { hairlineWidth } = require("nativewind/theme");
+
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  darkMode: "class",
+  content: ["./app/**/*.{ts,tsx}", "./components/**/*.{ts,tsx}"],
+  presets: [require("nativewind/preset")],
+  theme: {
+    extend: {
+      colors: {
+        border: "hsl(var(--border))",
+        input: "hsl(var(--input))",
+        ring: "hsl(var(--ring))",
+        background: "hsl(var(--background))",
+        foreground: "hsl(var(--foreground))",
+        primary: {
+          DEFAULT: "hsl(var(--primary))",
+          foreground: "hsl(var(--primary-foreground))",
+        },
+        secondary: {
+          DEFAULT: "hsl(var(--secondary))",
+          foreground: "hsl(var(--secondary-foreground))",
+        },
+        destructive: {
+          DEFAULT: "hsl(var(--destructive))",
+          foreground: "hsl(var(--destructive-foreground))",
+        },
+        muted: {
+          DEFAULT: "hsl(var(--muted))",
+          foreground: "hsl(var(--muted-foreground))",
+        },
+        accent: {
+          DEFAULT: "hsl(var(--accent))",
+          foreground: "hsl(var(--accent-foreground))",
+        },
+        popover: {
+          DEFAULT: "hsl(var(--popover))",
+          foreground: "hsl(var(--popover-foreground))",
+        },
+        card: {
+          DEFAULT: "hsl(var(--card))",
+          foreground: "hsl(var(--card-foreground))",
+        },
+      },
+      borderRadius: {
+        lg: "var(--radius)",
+        md: "calc(var(--radius) - 2px)",
+        sm: "calc(var(--radius) - 4px)",
+      },
+      borderWidth: {
+        hairline: hairlineWidth(),
+      },
+    },
+  },
+  future: {
+    hoverOnlyWhenSupported: true,
+  },
+  plugins: [require("tailwindcss-animate")],
+};
--- a/apps/mobile/tsconfig.json
+++ b/apps/mobile/tsconfig.json
@ -0,0 +1,18 @@
+{
+  "extends": "expo/tsconfig.base",
+  "compilerOptions": {
+    "strict": true,
+    "paths": {
+      "@/*": [
+        "./*"
+      ]
+    }
+  },
+  "include": [
+    "**/*.ts",
+    "**/*.tsx",
+    ".expo/types/**/*.ts",
+    "expo-env.d.ts",
+    "nativewind-env.d.ts"
+  ]
+}
--- a/docs/mobile/app-store-submission-guide.md
+++ b/docs/mobile/app-store-submission-guide.md
@ -0,0 +1,234 @@
+# App Store Submission Guide
+
+Complete guide for publishing the Expo React Native app to Apple App Store and Google Play Store.
+
+## 1. Prerequisites
+
+### Accounts & Fees
+
+| Platform | Cost | Notes |
+|----------|------|-------|
+| Apple Developer Program | $99/year | Required for App Store distribution |
+| Google Play Console | $25 one-time | Developer registration |
+| Expo Account | Free (paid plans available) | Required for EAS Build/Submit |
+
+- Apple Developer account review: 1-2 days
+- Google Play developer account review: days to weeks
+
+### Tools
+
+```bash
+npm install -g eas-cli
+eas login
+eas whoami  # verify login
+```
+
+## 2. Project Configuration
+
+### Initialize EAS
+
+```bash
+eas build:configure
+```
+
+Generates `eas.json` with three build profiles: `development`, `preview`, `production`.
+
+### Key `app.json` / `app.config.ts` Fields
+
+```jsonc
+{
+  "name": "Multica",
+  "slug": "multica",
+  "version": "1.0.0",
+  "ios": {
+    "bundleIdentifier": "com.multica.app",
+    "buildNumber": "1"          // increment on each submission
+  },
+  "android": {
+    "package": "com.multica.app",
+    "versionCode": 1            // increment on each submission
+  },
+  "icon": "./assets/icon.png",  // 1024x1024 PNG
+  "splash": {
+    "image": "./assets/splash.png"
+  }
+}
+```
+
+## 3. App Signing & Credentials
+
+### iOS
+
+- EAS auto-manages credentials (recommended): Distribution Certificate + Provisioning Profile
+- Or create manually in Apple Developer Portal
+
+### Android
+
+- EAS auto-generates Keystore (recommended), stored securely on EAS servers
+- **Back up Keystore** — losing it means you cannot update the published app
+- Play Store requires AAB (Android App Bundle) format
+
+## 4. Production Build
+
+```bash
+# iOS
+eas build --platform ios --profile production
+
+# Android
+eas build --platform android --profile production
+
+# Both
+eas build --platform all --profile production
+```
+
+Builds run in Expo cloud — no local Xcode or Android Studio needed.
+
+## 5. Store Listing Preparation
+
+### Required for Both Platforms
+
+#### Privacy Policy
+
+- **Mandatory** — must be a publicly accessible URL
+- Must clearly state:
+  - What data the app collects and how
+  - Whether data is shared with third parties
+  - Data retention and deletion policies
+  - How users can request data deletion
+- **2025 rule**: If data is sent to third-party AI, must disclose explicitly and obtain user consent
+- Tools: Termly, PrivacyPolicies.com, or custom page
+
+#### App Screenshots
+
+- **iOS**: Multiple sizes required (6.7", 6.5", 5.5" iPhone + iPad)
+- **Android**: 2-8 screenshots
+- Must accurately reflect current app interface
+
+#### App Icon
+
+- 1024x1024 high-resolution PNG
+- No alpha/transparency for iOS
+
+#### App Description
+
+- Short description (≤80 chars for Google Play)
+- Full description
+
+#### Support URL
+
+- A link where users can get help
+
+#### Account Deletion
+
+- If the app supports registration, users **must** be able to delete their account and data in-app
+- Both Apple and Google require this
+
+### Apple App Store Connect — Additional Requirements
+
+| Item | Details |
+|------|---------|
+| Privacy Nutrition Labels | Fill out data collection practices per category in App Store Connect |
+| App Review Information | Reviewer contact info, demo/test account credentials |
+| Content Rating | Age classification |
+| Export Compliance | Encryption usage declaration |
+| Info.plist Permission Strings | Clear purpose description for each permission (camera, location, etc.) |
+
+### Google Play Console — Additional Requirements
+
+| Item | Details |
+|------|---------|
+| Data Safety Form | Detail data collection and sharing (required even if no data is collected) |
+| Content Rating Questionnaire | IARC rating questionnaire |
+| Target Audience | Declare if the app targets children |
+| First Upload | Must be done manually via Play Console (Google Play API limitation) |
+
+## 6. Submit to Stores
+
+### Apple App Store
+
+```bash
+eas submit --platform ios
+```
+
+This uploads the build to **App Store Connect / TestFlight**. Then you must:
+
+1. Log into App Store Connect
+2. Select the uploaded build
+3. Associate it with a version
+4. Fill in all metadata, screenshots, privacy labels
+5. Submit for App Review
+
+### Google Play Store
+
+```bash
+eas submit --platform android
+```
+
+**First time**: Must upload AAB manually in Play Console.
+
+After initial upload:
+1. Navigate to Production → Create new release
+2. Upload AAB or use the EAS-submitted build
+3. Fill in description, screenshots, data safety form
+4. Submit for review
+
+### Auto-Submit (Optional)
+
+```bash
+eas build --platform all --profile production --auto-submit
+```
+
+## 7. App Review
+
+| | Apple | Google |
+|---|---|---|
+| Review time | Typically 24-48 hours | Hours to 7 days |
+| Common rejections | Incomplete features, misleading screenshots, missing privacy policy, unclear permission strings | Data safety form mismatch, policy violations |
+| After rejection | Fix issues, resubmit | Fix issues, resubmit |
+
+## 8. Post-Launch
+
+### OTA Updates (No Re-Review Needed)
+
+```bash
+eas update --branch production
+```
+
+- Only for JS/asset-level changes
+- Native code changes still require a new build + review
+
+### CI/CD Automation
+
+Create `.eas/workflows/build-and-submit.yml` to auto-build and submit on push to main.
+
+### Google Service Account Key (for Automated Android Submissions)
+
+1. Go to EAS dashboard → Credentials → Android
+2. Click Application identifier → Service Credentials
+3. Add Google Service Account Key
+
+## 9. Checklist
+
+- [ ] Register Apple Developer + Google Play Console accounts
+- [ ] Configure `app.json` and `eas.json`
+- [ ] Prepare app icon, splash screen, screenshots
+- [ ] Write and host privacy policy URL
+- [ ] Implement in-app account deletion (if registration exists)
+- [ ] Add Info.plist permission descriptions (iOS)
+- [ ] Run `eas build --platform all --profile production`
+- [ ] Create app in App Store Connect, fill metadata + privacy labels
+- [ ] Create app in Google Play Console, fill data safety form, manual first AAB upload
+- [ ] `eas submit` or submit manually for review
+- [ ] Wait for review approval → live
+- [ ] Set up `eas update` for OTA updates
+
+## References
+
+- [Expo: Submit to App Stores](https://docs.expo.dev/deploy/submit-to-app-stores/)
+- [Expo: EAS Submit](https://docs.expo.dev/submit/introduction/)
+- [Expo: Build Your Project](https://docs.expo.dev/deploy/build-project/)
+- [Expo: App Stores Best Practices](https://docs.expo.dev/distribution/app-stores/)
+- [Apple App Review Guidelines](https://developer.apple.com/app-store/review/guidelines/)
+- [Apple App Privacy Details](https://developer.apple.com/app-store/app-privacy-details/)
+- [Google Play Data Safety](https://support.google.com/googleplay/android-developer/answer/10787469)
+- [Google Play Developer Policy Center](https://play.google/developer-content-policy/)
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
--- a/src/agent/async-agent.ts
+++ b/src/agent/async-agent.ts
@ -14,6 +14,7 @@ export class AsyncAgent {
  private readonly channel = new Channel<ChannelItem>();
  private _closed = false;
  private queue: Promise<void> = Promise.resolve();
+  private closeCallbacks: Array<() => void> = [];
  readonly sessionId: string;

  constructor(options?: AgentOptions) {
@ -57,10 +58,33 @@ export class AsyncAgent {
    return this.channel;
  }

-  /** Close agent, stop all reads */
+  /** Returns a promise that resolves when the current message queue is drained */
+  waitForIdle(): Promise<void> {
+    return this.queue;
+  }
+
+  /** Register a callback to be invoked when the agent is closed */
+  onClose(callback: () => void): void {
+    if (this._closed) {
+      // Already closed, fire immediately
+      callback();
+      return;
+    }
+    this.closeCallbacks.push(callback);
+  }
+
+  /** Close agent, stop all reads, fire close callbacks */
  close(): void {
    if (this._closed) return;
    this._closed = true;
    this.channel.close();
+    for (const cb of this.closeCallbacks) {
+      try {
+        cb();
+      } catch {
+        // Don't let callback errors prevent other callbacks
+      }
+    }
+    this.closeCallbacks = [];
  }
 }
--- a/src/agent/runner.ts
+++ b/src/agent/runner.ts
@ -71,6 +71,7 @@ export class Agent {
  private readonly contextWindowGuard: ContextWindowGuardResult;
  private readonly debug: boolean;
  private readonly stderr: NodeJS.WritableStream;
+  private initialized = false;

  // Auth profile rotation state
  private readonly resolvedProvider: string;
@ -262,31 +263,6 @@ export class Agent {
    }
    this.agent.setTools(tools);

-    const restoredMessages = this.session.loadMessages();
-    if (restoredMessages.length > 0) {
-      if (this.debug) {
-        console.error(`[debug] Restoring ${restoredMessages.length} messages from session`);
-        for (const msg of restoredMessages) {
-          const msgAny = msg as any;
-          const content = Array.isArray(msgAny.content)
-            ? msgAny.content.map((c: any) => c.type || "text").join(", ")
-            : typeof msgAny.content;
-          console.error(`[debug]   ${msg.role}: ${content}`);
-          if (Array.isArray(msgAny.content)) {
-            for (const block of msgAny.content) {
-              if (block.type === "tool_use") {
-                console.error(`[debug]     tool_use id: ${block.id}, name: ${block.name}`);
-              }
-              if (block.type === "tool_result") {
-                console.error(`[debug]     tool_result tool_use_id: ${block.tool_use_id}`);
-              }
-            }
-          }
-        }
-      }
-      this.agent.replaceMessages(restoredMessages);
-    }
-
    this.session.saveMeta({
      provider: this.agent.state.model?.provider,
      model: this.agent.state.model?.id,
@ -310,6 +286,34 @@ export class Agent {
  }

  async run(prompt: string): Promise<AgentRunResult> {
+    if (!this.initialized) {
+      await this.session.repairIfNeeded((msg) => console.error(msg));
+      const restoredMessages = this.session.loadMessages();
+      if (restoredMessages.length > 0) {
+        if (this.debug) {
+          console.error(`[debug] Restoring ${restoredMessages.length} messages from session`);
+          for (const msg of restoredMessages) {
+            const msgAny = msg as any;
+            const content = Array.isArray(msgAny.content)
+              ? msgAny.content.map((c: any) => c.type || "text").join(", ")
+              : typeof msgAny.content;
+            console.error(`[debug]   ${msg.role}: ${content}`);
+            if (Array.isArray(msgAny.content)) {
+              for (const block of msgAny.content) {
+                if (block.type === "tool_use") {
+                  console.error(`[debug]     tool_use id: ${block.id}, name: ${block.name}`);
+                }
+                if (block.type === "tool_result") {
+                  console.error(`[debug]     tool_result tool_use_id: ${block.tool_use_id}`);
+                }
+              }
+            }
+          }
+        }
+        this.agent.replaceMessages(restoredMessages);
+      }
+      this.initialized = true;
+    }
    this.output.state.lastAssistantText = "";

    const canRotate = !this.pinnedProfile && this.profileCandidates.length > 1;
--- a/src/agent/session/session-file-repair.test.ts
+++ b/src/agent/session/session-file-repair.test.ts
@ -0,0 +1,105 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { repairSessionFileIfNeeded } from "./session-file-repair.js";
+import { acquireSessionWriteLock } from "./session-write-lock.js";
+
+vi.mock("./session-write-lock.js", async () => {
+  const actual = await vi.importActual<typeof import("./session-write-lock.js")>(
+    "./session-write-lock.js",
+  );
+  return {
+    ...actual,
+    acquireSessionWriteLock: vi.fn(actual.acquireSessionWriteLock),
+  };
+});
+
+describe("repairSessionFileIfNeeded", () => {
+  beforeEach(() => {
+    vi.mocked(acquireSessionWriteLock).mockClear();
+  });
+
+  it("rewrites session files that contain malformed lines", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "multica-session-repair-"));
+    const file = path.join(dir, "session.jsonl");
+    const meta = {
+      type: "meta",
+      meta: { provider: "kimi", model: "moonshot-v1-128k" },
+      timestamp: Date.now(),
+    };
+    const message = {
+      type: "message",
+      message: { role: "user", content: "hello" },
+      timestamp: Date.now(),
+    };
+
+    const content = `${JSON.stringify(meta)}\n${JSON.stringify(message)}\n{"type":"message"`;
+    await fs.writeFile(file, content, "utf-8");
+
+    const result = await repairSessionFileIfNeeded({ sessionFile: file });
+    expect(result.repaired).toBe(true);
+    expect(result.droppedLines).toBe(1);
+    expect(result.backupPath).toBeTruthy();
+
+    const repaired = await fs.readFile(file, "utf-8");
+    expect(repaired.trim().split("\n")).toHaveLength(2);
+
+    if (result.backupPath) {
+      const backup = await fs.readFile(result.backupPath, "utf-8");
+      expect(backup).toBe(content);
+    }
+  });
+
+  it("does not drop CRLF-terminated JSONL lines", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "multica-session-repair-"));
+    const file = path.join(dir, "session.jsonl");
+    const meta = {
+      type: "meta",
+      meta: { provider: "kimi", model: "moonshot-v1-128k" },
+      timestamp: Date.now(),
+    };
+    const message = {
+      type: "message",
+      message: { role: "user", content: "hello" },
+      timestamp: Date.now(),
+    };
+    const content = `${JSON.stringify(meta)}\r\n${JSON.stringify(message)}\r\n`;
+    await fs.writeFile(file, content, "utf-8");
+
+    const result = await repairSessionFileIfNeeded({ sessionFile: file });
+    expect(result.repaired).toBe(false);
+    expect(result.droppedLines).toBe(0);
+  });
+
+  it("returns reason when file is empty after dropping all lines", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "multica-session-repair-"));
+    const file = path.join(dir, "session.jsonl");
+    await fs.writeFile(file, "{broken\n{also broken\n", "utf-8");
+
+    const result = await repairSessionFileIfNeeded({ sessionFile: file });
+    expect(result.repaired).toBe(false);
+    expect(result.reason).toBe("empty session file");
+  });
+
+  it("returns a detailed reason when read errors are not ENOENT", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "multica-session-repair-"));
+    const warn = vi.fn();
+
+    const result = await repairSessionFileIfNeeded({ sessionFile: dir, warn });
+
+    expect(result.repaired).toBe(false);
+    expect(result.reason).toContain("failed to read session file");
+    expect(warn).toHaveBeenCalledTimes(1);
+  });
+
+  it("acquires a write lock while repairing", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "multica-session-repair-"));
+    const file = path.join(dir, "session.jsonl");
+    await fs.writeFile(file, "{broken\n{also broken\n", "utf-8");
+
+    await repairSessionFileIfNeeded({ sessionFile: file });
+
+    expect(vi.mocked(acquireSessionWriteLock)).toHaveBeenCalledTimes(1);
+  });
+});
--- a/src/agent/session/session-file-repair.ts
+++ b/src/agent/session/session-file-repair.ts
@ -0,0 +1,102 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { acquireSessionWriteLock } from "./session-write-lock.js";
+
+type RepairReport = {
+  repaired: boolean;
+  droppedLines: number;
+  backupPath?: string;
+  reason?: string;
+};
+
+export type { RepairReport };
+
+export async function repairSessionFileIfNeeded(params: {
+  sessionFile: string;
+  warn?: (message: string) => void;
+}): Promise<RepairReport> {
+  const sessionFile = params.sessionFile.trim();
+  if (!sessionFile) {
+    return { repaired: false, droppedLines: 0, reason: "missing session file" };
+  }
+
+  const lock = await acquireSessionWriteLock({ sessionFile });
+  try {
+    let content: string;
+    try {
+      content = await fs.readFile(sessionFile, "utf-8");
+    } catch (err) {
+      const code = (err as { code?: unknown } | undefined)?.code;
+      if (code === "ENOENT") {
+        return { repaired: false, droppedLines: 0, reason: "missing session file" };
+      }
+      const reason = `failed to read session file: ${err instanceof Error ? err.message : "unknown error"}`;
+      params.warn?.(`session file repair skipped: ${reason} (${path.basename(sessionFile)})`);
+      return { repaired: false, droppedLines: 0, reason };
+    }
+
+    const lines = content.split(/\r?\n/);
+    const entries: unknown[] = [];
+    let droppedLines = 0;
+
+    for (const line of lines) {
+      if (!line.trim()) {
+        continue;
+      }
+      try {
+        const entry = JSON.parse(line);
+        entries.push(entry);
+      } catch {
+        droppedLines += 1;
+      }
+    }
+
+    if (entries.length === 0) {
+      return { repaired: false, droppedLines, reason: "empty session file" };
+    }
+
+    if (droppedLines === 0) {
+      return { repaired: false, droppedLines: 0 };
+    }
+
+    const cleaned = `${entries.map((entry) => JSON.stringify(entry)).join("\n")}\n`;
+    const backupPath = `${sessionFile}.bak-${process.pid}-${Date.now()}`;
+    const tmpPath = `${sessionFile}.repair-${process.pid}-${Date.now()}.tmp`;
+    try {
+      const stat = await fs.stat(sessionFile).catch(() => null);
+      await fs.writeFile(backupPath, content, "utf-8");
+      if (stat) {
+        await fs.chmod(backupPath, stat.mode);
+      }
+      await fs.writeFile(tmpPath, cleaned, "utf-8");
+      if (stat) {
+        await fs.chmod(tmpPath, stat.mode);
+      }
+      await fs.rename(tmpPath, sessionFile);
+    } catch (err) {
+      try {
+        await fs.unlink(tmpPath);
+      } catch (cleanupErr) {
+        params.warn?.(
+          `session file repair cleanup failed: ${cleanupErr instanceof Error ? cleanupErr.message : "unknown error"} (${path.basename(
+            tmpPath,
+          )})`,
+        );
+      }
+      return {
+        repaired: false,
+        droppedLines,
+        reason: `repair failed: ${err instanceof Error ? err.message : "unknown error"}`,
+      };
+    }
+
+    params.warn?.(
+      `session file repaired: dropped ${droppedLines} malformed line(s) (${path.basename(
+        sessionFile,
+      )})`,
+    );
+    return { repaired: true, droppedLines, backupPath };
+  } finally {
+    await lock.release();
+  }
+}
--- a/src/agent/session/session-manager.ts
+++ b/src/agent/session/session-manager.ts
@ -1,9 +1,11 @@
 import type { AgentMessage } from "@mariozechner/pi-agent-core";
 import { getModel, type Model } from "@mariozechner/pi-ai";
 import type { SessionEntry, SessionMeta } from "./types.js";
-import { appendEntry, readEntries, writeEntries } from "./storage.js";
+import { appendEntry, readEntries, resolveSessionPath, writeEntries } from "./storage.js";
 import { compactMessages, compactMessagesAsync } from "./compaction.js";
 import { credentialManager } from "../credentials.js";
+import { repairSessionFileIfNeeded, type RepairReport } from "./session-file-repair.js";
+import { sanitizeToolCallInputs, sanitizeToolUseResultPairing } from "./session-transcript-repair.js";

 /** Get Kimi model for summarization (use a cheaper model than k2-thinking) */
 function getSummaryModel(): Model<any> {
@ -140,11 +142,19 @@ export class SessionManager {
    return readEntries(this.sessionId, { baseDir: this.baseDir });
  }

+  async repairIfNeeded(warn?: (message: string) => void): Promise<RepairReport> {
+    const filePath = resolveSessionPath(this.sessionId, { baseDir: this.baseDir });
+    return repairSessionFileIfNeeded({ sessionFile: filePath, warn });
+  }
+
  loadMessages(): AgentMessage[] {
    const entries = this.loadEntries();
-    return entries
+    let messages = entries
      .filter((entry) => entry.type === "message")
      .map((entry) => entry.message);
+    messages = sanitizeToolCallInputs(messages);
+    messages = sanitizeToolUseResultPairing(messages);
+    return messages;
  }

  loadMeta(): SessionMeta | undefined {
--- a/src/agent/session/session-transcript-repair.test.ts
+++ b/src/agent/session/session-transcript-repair.test.ts
@ -0,0 +1,150 @@
+import type { AgentMessage } from "@mariozechner/pi-agent-core";
+import { describe, expect, it } from "vitest";
+import {
+  sanitizeToolCallInputs,
+  sanitizeToolUseResultPairing,
+} from "./session-transcript-repair.js";
+
+describe("sanitizeToolUseResultPairing", () => {
+  it("moves tool results directly after tool calls and inserts missing results", () => {
+    const input = [
+      {
+        role: "assistant",
+        content: [
+          { type: "toolCall", id: "call_1", name: "read", arguments: {} },
+          { type: "toolCall", id: "call_2", name: "exec", arguments: {} },
+        ],
+      },
+      { role: "user", content: "user message that should come after tool use" },
+      {
+        role: "toolResult",
+        toolCallId: "call_2",
+        toolName: "exec",
+        content: [{ type: "text", text: "ok" }],
+        isError: false,
+      },
+    ] satisfies AgentMessage[];
+
+    const out = sanitizeToolUseResultPairing(input);
+    expect(out[0]?.role).toBe("assistant");
+    expect(out[1]?.role).toBe("toolResult");
+    expect((out[1] as { toolCallId?: string }).toolCallId).toBe("call_1");
+    expect(out[2]?.role).toBe("toolResult");
+    expect((out[2] as { toolCallId?: string }).toolCallId).toBe("call_2");
+    expect(out[3]?.role).toBe("user");
+  });
+
+  it("drops duplicate tool results for the same id within a span", () => {
+    const input = [
+      {
+        role: "assistant",
+        content: [{ type: "toolCall", id: "call_1", name: "read", arguments: {} }],
+      },
+      {
+        role: "toolResult",
+        toolCallId: "call_1",
+        toolName: "read",
+        content: [{ type: "text", text: "first" }],
+        isError: false,
+      },
+      {
+        role: "toolResult",
+        toolCallId: "call_1",
+        toolName: "read",
+        content: [{ type: "text", text: "second" }],
+        isError: false,
+      },
+      { role: "user", content: "ok" },
+    ] satisfies AgentMessage[];
+
+    const out = sanitizeToolUseResultPairing(input);
+    expect(out.filter((m) => m.role === "toolResult")).toHaveLength(1);
+  });
+
+  it("drops duplicate tool results for the same id across the transcript", () => {
+    const input = [
+      {
+        role: "assistant",
+        content: [{ type: "toolCall", id: "call_1", name: "read", arguments: {} }],
+      },
+      {
+        role: "toolResult",
+        toolCallId: "call_1",
+        toolName: "read",
+        content: [{ type: "text", text: "first" }],
+        isError: false,
+      },
+      { role: "assistant", content: [{ type: "text", text: "ok" }] },
+      {
+        role: "toolResult",
+        toolCallId: "call_1",
+        toolName: "read",
+        content: [{ type: "text", text: "second (duplicate)" }],
+        isError: false,
+      },
+    ] satisfies AgentMessage[];
+
+    const out = sanitizeToolUseResultPairing(input);
+    const results = out.filter((m) => m.role === "toolResult") as Array<{
+      toolCallId?: string;
+    }>;
+    expect(results).toHaveLength(1);
+    expect(results[0]?.toolCallId).toBe("call_1");
+  });
+
+  it("drops orphan tool results that do not match any tool call", () => {
+    const input = [
+      { role: "user", content: "hello" },
+      {
+        role: "toolResult",
+        toolCallId: "call_orphan",
+        toolName: "read",
+        content: [{ type: "text", text: "orphan" }],
+        isError: false,
+      },
+      {
+        role: "assistant",
+        content: [{ type: "text", text: "ok" }],
+      },
+    ] satisfies AgentMessage[];
+
+    const out = sanitizeToolUseResultPairing(input);
+    expect(out.some((m) => m.role === "toolResult")).toBe(false);
+    expect(out.map((m) => m.role)).toEqual(["user", "assistant"]);
+  });
+});
+
+describe("sanitizeToolCallInputs", () => {
+  it("drops tool calls missing input or arguments", () => {
+    const input: AgentMessage[] = [
+      {
+        role: "assistant",
+        content: [{ type: "toolCall", id: "call_1", name: "read" }],
+      },
+      { role: "user", content: "hello" },
+    ];
+
+    const out = sanitizeToolCallInputs(input);
+    expect(out.map((m) => m.role)).toEqual(["user"]);
+  });
+
+  it("keeps valid tool calls and preserves text blocks", () => {
+    const input: AgentMessage[] = [
+      {
+        role: "assistant",
+        content: [
+          { type: "text", text: "before" },
+          { type: "toolUse", id: "call_ok", name: "read", input: { path: "a" } },
+          { type: "toolCall", id: "call_drop", name: "read" },
+        ],
+      },
+    ];
+
+    const out = sanitizeToolCallInputs(input);
+    const assistant = out[0] as Extract<AgentMessage, { role: "assistant" }>;
+    const types = Array.isArray(assistant.content)
+      ? assistant.content.map((block) => (block as { type?: unknown }).type)
+      : [];
+    expect(types).toEqual(["text", "toolUse"]);
+  });
+});
--- a/src/agent/session/session-transcript-repair.ts
+++ b/src/agent/session/session-transcript-repair.ts
@ -0,0 +1,295 @@
+import type { AgentMessage } from "@mariozechner/pi-agent-core";
+
+type ToolCallLike = {
+  id: string;
+  name?: string;
+};
+
+const TOOL_CALL_TYPES = new Set(["toolCall", "toolUse", "functionCall"]);
+
+type ToolCallBlock = {
+  type?: unknown;
+  id?: unknown;
+  name?: unknown;
+  input?: unknown;
+  arguments?: unknown;
+};
+
+function extractToolCallsFromAssistant(
+  msg: Extract<AgentMessage, { role: "assistant" }>,
+): ToolCallLike[] {
+  const content = msg.content;
+  if (!Array.isArray(content)) {
+    return [];
+  }
+
+  const toolCalls: ToolCallLike[] = [];
+  for (const block of content) {
+    if (!block || typeof block !== "object") {
+      continue;
+    }
+    const rec = block as { type?: unknown; id?: unknown; name?: unknown };
+    if (typeof rec.id !== "string" || !rec.id) {
+      continue;
+    }
+
+    if (rec.type === "toolCall" || rec.type === "toolUse" || rec.type === "functionCall") {
+      toolCalls.push({
+        id: rec.id,
+        name: typeof rec.name === "string" ? rec.name : undefined,
+      });
+    }
+  }
+  return toolCalls;
+}
+
+function isToolCallBlock(block: unknown): block is ToolCallBlock {
+  if (!block || typeof block !== "object") {
+    return false;
+  }
+  const type = (block as { type?: unknown }).type;
+  return typeof type === "string" && TOOL_CALL_TYPES.has(type);
+}
+
+function hasToolCallInput(block: ToolCallBlock): boolean {
+  const hasInput = "input" in block ? block.input !== undefined && block.input !== null : false;
+  const hasArguments =
+    "arguments" in block ? block.arguments !== undefined && block.arguments !== null : false;
+  return hasInput || hasArguments;
+}
+
+function extractToolResultId(msg: Extract<AgentMessage, { role: "toolResult" }>): string | null {
+  const toolCallId = (msg as { toolCallId?: unknown }).toolCallId;
+  if (typeof toolCallId === "string" && toolCallId) {
+    return toolCallId;
+  }
+  const toolUseId = (msg as { toolUseId?: unknown }).toolUseId;
+  if (typeof toolUseId === "string" && toolUseId) {
+    return toolUseId;
+  }
+  return null;
+}
+
+function makeMissingToolResult(params: {
+  toolCallId: string;
+  toolName?: string;
+}): Extract<AgentMessage, { role: "toolResult" }> {
+  return {
+    role: "toolResult",
+    toolCallId: params.toolCallId,
+    toolName: params.toolName ?? "unknown",
+    content: [
+      {
+        type: "text",
+        text: "[multica] missing tool result in session history; inserted synthetic error result for transcript repair.",
+      },
+    ],
+    isError: true,
+    timestamp: Date.now(),
+  } as Extract<AgentMessage, { role: "toolResult" }>;
+}
+
+export { makeMissingToolResult };
+
+export type ToolCallInputRepairReport = {
+  messages: AgentMessage[];
+  droppedToolCalls: number;
+  droppedAssistantMessages: number;
+};
+
+export function repairToolCallInputs(messages: AgentMessage[]): ToolCallInputRepairReport {
+  let droppedToolCalls = 0;
+  let droppedAssistantMessages = 0;
+  let changed = false;
+  const out: AgentMessage[] = [];
+
+  for (const msg of messages) {
+    if (!msg || typeof msg !== "object") {
+      out.push(msg);
+      continue;
+    }
+
+    if (msg.role !== "assistant" || !Array.isArray(msg.content)) {
+      out.push(msg);
+      continue;
+    }
+
+    const nextContent = [];
+    let droppedInMessage = 0;
+
+    for (const block of msg.content) {
+      if (isToolCallBlock(block) && !hasToolCallInput(block)) {
+        droppedToolCalls += 1;
+        droppedInMessage += 1;
+        changed = true;
+        continue;
+      }
+      nextContent.push(block);
+    }
+
+    if (droppedInMessage > 0) {
+      if (nextContent.length === 0) {
+        droppedAssistantMessages += 1;
+        changed = true;
+        continue;
+      }
+      out.push({ ...msg, content: nextContent });
+      continue;
+    }
+
+    out.push(msg);
+  }
+
+  return {
+    messages: changed ? out : messages,
+    droppedToolCalls,
+    droppedAssistantMessages,
+  };
+}
+
+export function sanitizeToolCallInputs(messages: AgentMessage[]): AgentMessage[] {
+  return repairToolCallInputs(messages).messages;
+}
+
+export function sanitizeToolUseResultPairing(messages: AgentMessage[]): AgentMessage[] {
+  return repairToolUseResultPairing(messages).messages;
+}
+
+export type ToolUseRepairReport = {
+  messages: AgentMessage[];
+  added: Array<Extract<AgentMessage, { role: "toolResult" }>>;
+  droppedDuplicateCount: number;
+  droppedOrphanCount: number;
+  moved: boolean;
+};
+
+export function repairToolUseResultPairing(messages: AgentMessage[]): ToolUseRepairReport {
+  const out: AgentMessage[] = [];
+  const added: Array<Extract<AgentMessage, { role: "toolResult" }>> = [];
+  const seenToolResultIds = new Set<string>();
+  let droppedDuplicateCount = 0;
+  let droppedOrphanCount = 0;
+  let moved = false;
+  let changed = false;
+
+  const pushToolResult = (msg: Extract<AgentMessage, { role: "toolResult" }>) => {
+    const id = extractToolResultId(msg);
+    if (id && seenToolResultIds.has(id)) {
+      droppedDuplicateCount += 1;
+      changed = true;
+      return;
+    }
+    if (id) {
+      seenToolResultIds.add(id);
+    }
+    out.push(msg);
+  };
+
+  for (let i = 0; i < messages.length; i += 1) {
+    const msg = messages[i];
+    if (!msg || typeof msg !== "object") {
+      out.push(msg);
+      continue;
+    }
+
+    const role = (msg as { role?: unknown }).role;
+    if (role !== "assistant") {
+      if (role !== "toolResult") {
+        out.push(msg);
+      } else {
+        droppedOrphanCount += 1;
+        changed = true;
+      }
+      continue;
+    }
+
+    const assistant = msg as Extract<AgentMessage, { role: "assistant" }>;
+    const toolCalls = extractToolCallsFromAssistant(assistant);
+    if (toolCalls.length === 0) {
+      out.push(msg);
+      continue;
+    }
+
+    const toolCallIds = new Set(toolCalls.map((t) => t.id));
+
+    const spanResultsById = new Map<string, Extract<AgentMessage, { role: "toolResult" }>>();
+    const remainder: AgentMessage[] = [];
+
+    let j = i + 1;
+    for (; j < messages.length; j += 1) {
+      const next = messages[j];
+      if (!next || typeof next !== "object") {
+        remainder.push(next);
+        continue;
+      }
+
+      const nextRole = (next as { role?: unknown }).role;
+      if (nextRole === "assistant") {
+        break;
+      }
+
+      if (nextRole === "toolResult") {
+        const toolResult = next as Extract<AgentMessage, { role: "toolResult" }>;
+        const id = extractToolResultId(toolResult);
+        if (id && toolCallIds.has(id)) {
+          if (seenToolResultIds.has(id)) {
+            droppedDuplicateCount += 1;
+            changed = true;
+            continue;
+          }
+          if (!spanResultsById.has(id)) {
+            spanResultsById.set(id, toolResult);
+          }
+          continue;
+        }
+      }
+
+      if (nextRole !== "toolResult") {
+        remainder.push(next);
+      } else {
+        droppedOrphanCount += 1;
+        changed = true;
+      }
+    }
+
+    out.push(msg);
+
+    if (spanResultsById.size > 0 && remainder.length > 0) {
+      moved = true;
+      changed = true;
+    }
+
+    for (const call of toolCalls) {
+      const existing = spanResultsById.get(call.id);
+      if (existing) {
+        pushToolResult(existing);
+      } else {
+        const missing = makeMissingToolResult({
+          toolCallId: call.id,
+          toolName: call.name,
+        });
+        added.push(missing);
+        changed = true;
+        pushToolResult(missing);
+      }
+    }
+
+    for (const rem of remainder) {
+      if (!rem || typeof rem !== "object") {
+        out.push(rem);
+        continue;
+      }
+      out.push(rem);
+    }
+    i = j - 1;
+  }
+
+  const changedOrMoved = changed || moved;
+  return {
+    messages: changedOrMoved ? out : messages,
+    added,
+    droppedDuplicateCount,
+    droppedOrphanCount,
+    moved: changedOrMoved,
+  };
+}
--- a/src/agent/session/session-write-lock.test.ts
+++ b/src/agent/session/session-write-lock.test.ts
@ -0,0 +1,194 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { __testing, acquireSessionWriteLock } from "./session-write-lock.js";
+
+describe("acquireSessionWriteLock", () => {
+  it("reuses locks across symlinked session paths", async () => {
+    if (process.platform === "win32") {
+      expect(true).toBe(true);
+      return;
+    }
+
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), "multica-lock-"));
+    try {
+      const realDir = path.join(root, "real");
+      const linkDir = path.join(root, "link");
+      await fs.mkdir(realDir, { recursive: true });
+      await fs.symlink(realDir, linkDir);
+
+      const sessionReal = path.join(realDir, "sessions.json");
+      const sessionLink = path.join(linkDir, "sessions.json");
+
+      const lockA = await acquireSessionWriteLock({ sessionFile: sessionReal, timeoutMs: 500 });
+      const lockB = await acquireSessionWriteLock({ sessionFile: sessionLink, timeoutMs: 500 });
+
+      await lockB.release();
+      await lockA.release();
+    } finally {
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it("keeps the lock file until the last release", async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), "multica-lock-"));
+    try {
+      const sessionFile = path.join(root, "sessions.json");
+      const lockPath = `${sessionFile}.lock`;
+
+      const lockA = await acquireSessionWriteLock({ sessionFile, timeoutMs: 500 });
+      const lockB = await acquireSessionWriteLock({ sessionFile, timeoutMs: 500 });
+
+      await expect(fs.access(lockPath)).resolves.toBeUndefined();
+      await lockA.release();
+      await expect(fs.access(lockPath)).resolves.toBeUndefined();
+      await lockB.release();
+      await expect(fs.access(lockPath)).rejects.toThrow();
+    } finally {
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it("reclaims stale lock files", async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), "multica-lock-"));
+    try {
+      const sessionFile = path.join(root, "sessions.json");
+      const lockPath = `${sessionFile}.lock`;
+      await fs.writeFile(
+        lockPath,
+        JSON.stringify({ pid: 123456, createdAt: new Date(Date.now() - 60_000).toISOString() }),
+        "utf8",
+      );
+
+      const lock = await acquireSessionWriteLock({ sessionFile, timeoutMs: 500, staleMs: 10 });
+      const raw = await fs.readFile(lockPath, "utf8");
+      const payload = JSON.parse(raw) as { pid: number };
+
+      expect(payload.pid).toBe(process.pid);
+      await lock.release();
+    } finally {
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it("does not delete recent lock files with invalid payloads", async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), "multica-lock-"));
+    try {
+      const sessionFile = path.join(root, "sessions.json");
+      const lockPath = `${sessionFile}.lock`;
+      await fs.writeFile(lockPath, "{", "utf8");
+
+      await expect(
+        acquireSessionWriteLock({ sessionFile, timeoutMs: 200, staleMs: 60_000 }),
+      ).rejects.toThrow(/timeout/);
+
+      await expect(fs.access(lockPath)).resolves.toBeUndefined();
+    } finally {
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it("reclaims invalid lock files when mtime is stale", async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), "multica-lock-"));
+    try {
+      const sessionFile = path.join(root, "sessions.json");
+      const lockPath = `${sessionFile}.lock`;
+      await fs.writeFile(lockPath, "{", "utf8");
+      const old = new Date(Date.now() - 60_000);
+      await fs.utimes(lockPath, old, old);
+
+      const lock = await acquireSessionWriteLock({ sessionFile, timeoutMs: 500, staleMs: 10 });
+
+      await lock.release();
+    } finally {
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it("removes held locks on termination signals", async () => {
+    const signals = ["SIGINT", "SIGTERM", "SIGQUIT", "SIGABRT"] as const;
+    for (const signal of signals) {
+      const root = await fs.mkdtemp(path.join(os.tmpdir(), "multica-lock-cleanup-"));
+      // Prevent the signal from actually killing the vitest worker
+      const keepAlive = () => {};
+      process.on(signal, keepAlive);
+      try {
+        const sessionFile = path.join(root, "sessions.json");
+        const lockPath = `${sessionFile}.lock`;
+        await acquireSessionWriteLock({ sessionFile, timeoutMs: 500 });
+
+        __testing.handleTerminationSignal(signal);
+
+        await expect(fs.stat(lockPath)).rejects.toThrow();
+      } finally {
+        process.off(signal, keepAlive);
+        await fs.rm(root, { recursive: true, force: true });
+      }
+    }
+  });
+
+  it("registers cleanup for SIGQUIT and SIGABRT", () => {
+    expect(__testing.cleanupSignals).toContain("SIGQUIT");
+    expect(__testing.cleanupSignals).toContain("SIGABRT");
+  });
+
+  it("cleans up locks on SIGINT without removing other handlers", async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), "multica-lock-"));
+    const originalKill = process.kill.bind(process) as typeof process.kill;
+    const killCalls: Array<NodeJS.Signals | undefined> = [];
+    let otherHandlerCalled = false;
+
+    process.kill = ((pid: number, signal?: NodeJS.Signals) => {
+      killCalls.push(signal);
+      return true;
+    }) as typeof process.kill;
+
+    const otherHandler = () => {
+      otherHandlerCalled = true;
+    };
+
+    process.on("SIGINT", otherHandler);
+
+    try {
+      const sessionFile = path.join(root, "sessions.json");
+      const lockPath = `${sessionFile}.lock`;
+      await acquireSessionWriteLock({ sessionFile, timeoutMs: 500 });
+
+      process.emit("SIGINT");
+
+      await expect(fs.access(lockPath)).rejects.toThrow();
+      expect(otherHandlerCalled).toBe(true);
+      expect(killCalls).toEqual([]);
+    } finally {
+      process.off("SIGINT", otherHandler);
+      process.kill = originalKill;
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it("cleans up locks via releaseAllLocksSync", async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), "multica-lock-"));
+    try {
+      const sessionFile = path.join(root, "sessions.json");
+      const lockPath = `${sessionFile}.lock`;
+      await acquireSessionWriteLock({ sessionFile, timeoutMs: 500 });
+
+      __testing.releaseAllLocksSync();
+
+      await expect(fs.access(lockPath)).rejects.toThrow();
+    } finally {
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it("keeps other signal listeners registered", () => {
+    const keepAlive = () => {};
+    process.on("SIGINT", keepAlive);
+
+    __testing.handleTerminationSignal("SIGINT");
+
+    expect(process.listeners("SIGINT")).toContain(keepAlive);
+    process.off("SIGINT", keepAlive);
+  });
+});
--- a/src/agent/session/session-write-lock.ts
+++ b/src/agent/session/session-write-lock.ts
@ -0,0 +1,226 @@
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+type LockFilePayload = {
+  pid: number;
+  createdAt: string;
+};
+
+type HeldLock = {
+  count: number;
+  handle: fs.FileHandle;
+  lockPath: string;
+};
+
+const HELD_LOCKS = new Map<string, HeldLock>();
+const CLEANUP_SIGNALS = ["SIGINT", "SIGTERM", "SIGQUIT", "SIGABRT"] as const;
+type CleanupSignal = (typeof CLEANUP_SIGNALS)[number];
+const cleanupHandlers = new Map<CleanupSignal, () => void>();
+
+function isAlive(pid: number): boolean {
+  if (!Number.isFinite(pid) || pid <= 0) {
+    return false;
+  }
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Synchronously release all held locks.
+ * Used during process exit when async operations aren't reliable.
+ */
+function releaseAllLocksSync(): void {
+  for (const [sessionFile, held] of HELD_LOCKS) {
+    try {
+      if (typeof held.handle.close === "function") {
+        void held.handle.close().catch(() => {});
+      }
+    } catch {
+      // Ignore errors during cleanup - best effort
+    }
+    try {
+      fsSync.rmSync(held.lockPath, { force: true });
+    } catch {
+      // Ignore errors during cleanup - best effort
+    }
+    HELD_LOCKS.delete(sessionFile);
+  }
+}
+
+let cleanupRegistered = false;
+
+function handleTerminationSignal(signal: CleanupSignal): void {
+  releaseAllLocksSync();
+  const shouldReraise = process.listenerCount(signal) === 1;
+  if (shouldReraise) {
+    const handler = cleanupHandlers.get(signal);
+    if (handler) {
+      process.off(signal, handler);
+    }
+    try {
+      process.kill(process.pid, signal);
+    } catch {
+      // Ignore errors during shutdown
+    }
+  }
+}
+
+function registerCleanupHandlers(): void {
+  if (cleanupRegistered) {
+    return;
+  }
+  cleanupRegistered = true;
+
+  // Cleanup on normal exit and process.exit() calls
+  process.on("exit", () => {
+    releaseAllLocksSync();
+  });
+
+  // Handle termination signals
+  for (const signal of CLEANUP_SIGNALS) {
+    try {
+      const handler = () => handleTerminationSignal(signal);
+      cleanupHandlers.set(signal, handler);
+      process.on(signal, handler);
+    } catch {
+      // Ignore unsupported signals on this platform.
+    }
+  }
+}
+
+async function readLockPayload(lockPath: string): Promise<LockFilePayload | null> {
+  try {
+    const raw = await fs.readFile(lockPath, "utf8");
+    const parsed = JSON.parse(raw) as Partial<LockFilePayload>;
+    if (typeof parsed.pid !== "number") {
+      return null;
+    }
+    if (typeof parsed.createdAt !== "string") {
+      return null;
+    }
+    return { pid: parsed.pid, createdAt: parsed.createdAt };
+  } catch {
+    return null;
+  }
+}
+
+async function getLockAgeMs(lockPath: string): Promise<number | null> {
+  try {
+    const stat = await fs.stat(lockPath);
+    return Date.now() - stat.mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+export async function acquireSessionWriteLock(params: {
+  sessionFile: string;
+  timeoutMs?: number;
+  staleMs?: number;
+}): Promise<{
+  release: () => Promise<void>;
+}> {
+  registerCleanupHandlers();
+  const timeoutMs = params.timeoutMs ?? 10_000;
+  const staleMs = params.staleMs ?? 30 * 60 * 1000;
+  const sessionFile = path.resolve(params.sessionFile);
+  const sessionDir = path.dirname(sessionFile);
+  await fs.mkdir(sessionDir, { recursive: true });
+  let normalizedDir = sessionDir;
+  try {
+    normalizedDir = await fs.realpath(sessionDir);
+  } catch {
+    // Fall back to the resolved path if realpath fails (permissions, transient FS).
+  }
+  const normalizedSessionFile = path.join(normalizedDir, path.basename(sessionFile));
+  const lockPath = `${normalizedSessionFile}.lock`;
+
+  const held = HELD_LOCKS.get(normalizedSessionFile);
+  if (held) {
+    held.count += 1;
+    return {
+      release: async () => {
+        const current = HELD_LOCKS.get(normalizedSessionFile);
+        if (!current) {
+          return;
+        }
+        current.count -= 1;
+        if (current.count > 0) {
+          return;
+        }
+        HELD_LOCKS.delete(normalizedSessionFile);
+        await current.handle.close();
+        await fs.rm(current.lockPath, { force: true });
+      },
+    };
+  }
+
+  const startedAt = Date.now();
+  let attempt = 0;
+  while (Date.now() - startedAt < timeoutMs) {
+    attempt += 1;
+    try {
+      const handle = await fs.open(lockPath, "wx");
+      await handle.writeFile(
+        JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }, null, 2),
+        "utf8",
+      );
+      HELD_LOCKS.set(normalizedSessionFile, { count: 1, handle, lockPath });
+      return {
+        release: async () => {
+          const current = HELD_LOCKS.get(normalizedSessionFile);
+          if (!current) {
+            return;
+          }
+          current.count -= 1;
+          if (current.count > 0) {
+            return;
+          }
+          HELD_LOCKS.delete(normalizedSessionFile);
+          await current.handle.close();
+          await fs.rm(current.lockPath, { force: true });
+        },
+      };
+    } catch (err) {
+      const code = (err as { code?: unknown }).code;
+      if (code !== "EEXIST") {
+        throw err;
+      }
+      const payload = await readLockPayload(lockPath);
+      if (payload) {
+        const createdAt = payload.createdAt ? Date.parse(payload.createdAt) : NaN;
+        const stale = !Number.isFinite(createdAt) || Date.now() - createdAt > staleMs;
+        const alive = payload.pid ? isAlive(payload.pid) : false;
+        if (stale || !alive) {
+          await fs.rm(lockPath, { force: true });
+          continue;
+        }
+      } else {
+        const ageMs = await getLockAgeMs(lockPath);
+        const stale = ageMs !== null && ageMs > staleMs;
+        if (stale) {
+          await fs.rm(lockPath, { force: true });
+          continue;
+        }
+      }
+
+      const delay = Math.min(1000, 50 * attempt);
+      await new Promise((r) => setTimeout(r, delay));
+    }
+  }
+
+  const payload = await readLockPayload(lockPath);
+  const owner = payload?.pid ? `pid=${payload.pid}` : "unknown";
+  throw new Error(`session file locked (timeout ${timeoutMs}ms): ${owner} ${lockPath}`);
+}
+
+export const __testing = {
+  cleanupSignals: [...CLEANUP_SIGNALS],
+  handleTerminationSignal,
+  releaseAllLocksSync,
+};
--- a/src/agent/session/storage.ts
+++ b/src/agent/session/storage.ts
@ -3,6 +3,7 @@ import { existsSync, mkdirSync, readFileSync } from "fs";
 import { appendFile, writeFile } from "fs/promises";
 import type { SessionEntry } from "./types.js";
 import { DATA_DIR } from "../../shared/index.js";
+import { acquireSessionWriteLock } from "./session-write-lock.js";

 export type SessionStorageOptions = {
  baseDir?: string | undefined;
@ -50,7 +51,12 @@ export async function appendEntry(
 ) {
  ensureSessionDir(sessionId, options);
  const filePath = resolveSessionPath(sessionId, options);
-  await appendFile(filePath, `${JSON.stringify(entry)}\n`, "utf8");
+  const lock = await acquireSessionWriteLock({ sessionFile: filePath });
+  try {
+    await appendFile(filePath, `${JSON.stringify(entry)}\n`, "utf8");
+  } finally {
+    await lock.release();
+  }
 }

 export async function writeEntries(
@ -60,6 +66,11 @@ export async function writeEntries(
 ) {
  ensureSessionDir(sessionId, options);
  const filePath = resolveSessionPath(sessionId, options);
-  const content = entries.map((entry) => JSON.stringify(entry)).join("\n");
-  await writeFile(filePath, content ? `${content}\n` : "", "utf8");
+  const lock = await acquireSessionWriteLock({ sessionFile: filePath });
+  try {
+    const content = entries.map((entry) => JSON.stringify(entry)).join("\n");
+    await writeFile(filePath, content ? `${content}\n` : "", "utf8");
+  } finally {
+    await lock.release();
+  }
 }
--- a/src/agent/subagent/announce.test.ts
+++ b/src/agent/subagent/announce.test.ts
@ -0,0 +1,127 @@
+import { describe, it, expect } from "vitest";
+import { buildSubagentSystemPrompt, formatAnnouncementMessage } from "./announce.js";
+import type { FormatAnnouncementParams } from "./announce.js";
+
+describe("buildSubagentSystemPrompt", () => {
+  it("includes task and session context", () => {
+    const prompt = buildSubagentSystemPrompt({
+      requesterSessionId: "parent-123",
+      childSessionId: "child-456",
+      task: "Analyze the auth module for security issues",
+    });
+
+    expect(prompt).toContain("You are a subagent spawned to complete a specific task");
+    expect(prompt).toContain("Analyze the auth module for security issues");
+    expect(prompt).toContain("parent-123");
+    expect(prompt).toContain("child-456");
+    expect(prompt).toContain("Do NOT spawn nested subagents");
+  });
+
+  it("includes label when provided", () => {
+    const prompt = buildSubagentSystemPrompt({
+      requesterSessionId: "parent-123",
+      childSessionId: "child-456",
+      label: "Security Audit",
+      task: "Check for vulnerabilities",
+    });
+
+    expect(prompt).toContain('Label: "Security Audit"');
+  });
+
+  it("omits label line when not provided", () => {
+    const prompt = buildSubagentSystemPrompt({
+      requesterSessionId: "parent-123",
+      childSessionId: "child-456",
+      task: "Do something",
+    });
+
+    expect(prompt).not.toContain("Label:");
+  });
+});
+
+describe("formatAnnouncementMessage", () => {
+  const baseParams: FormatAnnouncementParams = {
+    runId: "run-1",
+    childSessionId: "child-456",
+    requesterSessionId: "parent-123",
+    task: "Analyze code",
+    label: "Code Analysis",
+    cleanup: "delete",
+    outcome: { status: "ok" },
+    startedAt: 1000000,
+    endedAt: 1030000,
+  };
+
+  it("formats successful completion", () => {
+    const msg = formatAnnouncementMessage({
+      ...baseParams,
+      findings: "Found 3 issues in the auth module.",
+    });
+
+    expect(msg).toContain('"Code Analysis" just completed successfully');
+    expect(msg).toContain("Found 3 issues in the auth module.");
+    expect(msg).toContain("runtime 30s");
+    expect(msg).toContain("session child-456");
+  });
+
+  it("formats error outcome", () => {
+    const msg = formatAnnouncementMessage({
+      ...baseParams,
+      outcome: { status: "error", error: "API key expired" },
+    });
+
+    expect(msg).toContain("failed: API key expired");
+  });
+
+  it("formats timeout outcome", () => {
+    const msg = formatAnnouncementMessage({
+      ...baseParams,
+      outcome: { status: "timeout" },
+    });
+
+    expect(msg).toContain("timed out");
+  });
+
+  it("shows (no output) when findings is not provided", () => {
+    const msg = formatAnnouncementMessage(baseParams);
+
+    expect(msg).toContain("(no output)");
+  });
+
+  it("uses task text when label is not provided", () => {
+    const paramsNoLabel: FormatAnnouncementParams = {
+      ...baseParams,
+      label: undefined,
+    };
+    const msg = formatAnnouncementMessage(paramsNoLabel);
+
+    expect(msg).toContain('"Analyze code"');
+  });
+
+  it("formats runtime for minutes", () => {
+    const msg = formatAnnouncementMessage({
+      ...baseParams,
+      startedAt: 1000000,
+      endedAt: 1150000, // 150 seconds = 2m30s
+    });
+
+    expect(msg).toContain("runtime 2m30s");
+  });
+
+  it("formats runtime for hours", () => {
+    const msg = formatAnnouncementMessage({
+      ...baseParams,
+      startedAt: 1000000,
+      endedAt: 4600000, // 3600 seconds = 1h
+    });
+
+    expect(msg).toContain("runtime 1h");
+  });
+
+  it("includes summarization instruction", () => {
+    const msg = formatAnnouncementMessage(baseParams);
+
+    expect(msg).toContain("Summarize this naturally for the user");
+    expect(msg).toContain("NO_REPLY");
+  });
+});
--- a/src/agent/subagent/announce.ts
+++ b/src/agent/subagent/announce.ts
@ -0,0 +1,226 @@
+/**
+ * Subagent announcement flow.
+ *
+ * Handles result propagation from child → parent agent:
+ * - Builds system prompts for child agents
+ * - Reads child session output
+ * - Formats and delivers announcement messages
+ */
+
+import { readEntries } from "../session/storage.js";
+import { getHub } from "../../hub/hub-singleton.js";
+import type {
+  SubagentAnnounceParams,
+  SubagentRunOutcome,
+  SubagentSystemPromptParams,
+} from "./types.js";
+
+/**
+ * Build the system prompt injected into a subagent session.
+ */
+export function buildSubagentSystemPrompt(params: SubagentSystemPromptParams): string {
+  const { requesterSessionId, childSessionId, label, task } = params;
+
+  const lines: string[] = [
+    "You are a subagent spawned to complete a specific task.",
+    "",
+    "## Rules",
+    "- Stay focused on the assigned task below.",
+    "- Complete the task thoroughly and report your findings.",
+    "- Do NOT initiate side actions unrelated to the task.",
+    "- Do NOT attempt to communicate with the user directly.",
+    "- Do NOT spawn nested subagents.",
+    "- Your session is ephemeral and will be cleaned up after completion.",
+    "",
+    "## Context",
+    `Requester session: ${requesterSessionId}`,
+    `Child session: ${childSessionId}`,
+  ];
+
+  if (label) {
+    lines.push(`Label: "${label}"`);
+  }
+
+  lines.push("", "## Task", task);
+
+  return lines.join("\n");
+}
+
+/**
+ * Read the latest assistant reply from a session's JSONL file.
+ */
+export function readLatestAssistantReply(sessionId: string): string | undefined {
+  const entries = readEntries(sessionId);
+
+  // Walk backwards to find last assistant message
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const entry = entries[i]!;
+    if (entry.type !== "message") continue;
+
+    const message = entry.message;
+    if (message.role !== "assistant") continue;
+
+    return extractAssistantText(message);
+  }
+
+  return undefined;
+}
+
+/**
+ * Extract text content from an assistant message.
+ * AgentMessage.content for assistant is (TextContent | ThinkingContent | ToolCall)[].
+ */
+function extractAssistantText(message: { role: string; content: unknown }): string {
+  const content = message.content;
+  if (typeof content === "string") {
+    return sanitizeText(content);
+  }
+
+  if (!Array.isArray(content)) return "";
+
+  const textParts: string[] = [];
+  for (const block of content) {
+    if (block && typeof block === "object" && "type" in block && block.type === "text" && "text" in block) {
+      textParts.push(String(block.text));
+    }
+  }
+
+  return sanitizeText(textParts.join("\n"));
+}
+
+/**
+ * Strip thinking tags and tool markers from text.
+ */
+function sanitizeText(text: string): string {
+  return text
+    .replace(/<thinking>[\s\S]*?<\/thinking>/g, "")
+    .replace(/<tool_call>[\s\S]*?<\/tool_call>/g, "")
+    .trim();
+}
+
+/**
+ * Format the duration between two timestamps as a human-readable string.
+ */
+function formatDuration(startMs: number, endMs: number): string {
+  const totalSeconds = Math.round((endMs - startMs) / 1000);
+  if (totalSeconds < 60) return `${totalSeconds}s`;
+
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  if (minutes < 60) return seconds > 0 ? `${minutes}m${seconds}s` : `${minutes}m`;
+
+  const hours = Math.floor(minutes / 60);
+  const remainingMinutes = minutes % 60;
+  return remainingMinutes > 0 ? `${hours}h${remainingMinutes}m` : `${hours}h`;
+}
+
+/**
+ * Format a status label from an outcome.
+ */
+function formatStatusLabel(outcome: SubagentRunOutcome | undefined): string {
+  if (!outcome) return "completed with unknown status";
+  switch (outcome.status) {
+    case "ok":
+      return "completed successfully";
+    case "error":
+      return outcome.error ? `failed: ${outcome.error}` : "failed";
+    case "timeout":
+      return "timed out";
+    default:
+      return "completed with unknown status";
+  }
+}
+
+/** Parameters for formatAnnouncementMessage */
+export interface FormatAnnouncementParams {
+  runId: string;
+  childSessionId: string;
+  requesterSessionId: string;
+  task: string;
+  label?: string | undefined;
+  cleanup: "delete" | "keep";
+  outcome?: SubagentRunOutcome | undefined;
+  startedAt?: number | undefined;
+  endedAt?: number | undefined;
+  findings?: string | undefined;
+}
+
+/**
+ * Format the announcement message sent to the parent agent.
+ */
+export function formatAnnouncementMessage(params: FormatAnnouncementParams): string {
+  const { task, label, outcome, findings, startedAt, endedAt, childSessionId } = params;
+  const displayName = label || task.slice(0, 60);
+  const statusLabel = formatStatusLabel(outcome);
+
+  const parts: string[] = [
+    `A background task "${displayName}" just ${statusLabel}.`,
+    "",
+    "Findings:",
+    findings || "(no output)",
+  ];
+
+  // Stats line
+  const stats: string[] = [];
+  if (startedAt && endedAt) {
+    stats.push(`runtime ${formatDuration(startedAt, endedAt)}`);
+  }
+  stats.push(`session ${childSessionId}`);
+
+  parts.push("", `Stats: ${stats.join(" • ")}`);
+
+  parts.push(
+    "",
+    "Summarize this naturally for the user. Keep it brief (1-2 sentences).",
+    "Flow it into the conversation naturally.",
+    "Do not mention technical details like session IDs or that this was a background task.",
+    "You can respond with NO_REPLY if no announcement is needed (e.g., internal task with no user-facing result).",
+  );
+
+  return parts.join("\n");
+}
+
+/**
+ * Run the full subagent announcement flow:
+ * 1. Read child's last assistant reply
+ * 2. Format announcement message
+ * 3. Send to parent agent via Hub
+ */
+export function runSubagentAnnounceFlow(params: SubagentAnnounceParams): boolean {
+  const { requesterSessionId, childSessionId } = params;
+
+  // Read child's final output
+  const findings = readLatestAssistantReply(childSessionId);
+
+  // Format the announcement
+  const message = formatAnnouncementMessage({
+    runId: params.runId,
+    childSessionId: params.childSessionId,
+    requesterSessionId: params.requesterSessionId,
+    task: params.task,
+    label: params.label,
+    cleanup: params.cleanup,
+    outcome: params.outcome,
+    startedAt: params.startedAt,
+    endedAt: params.endedAt,
+    findings,
+  });
+
+  // Deliver to parent agent via Hub
+  try {
+    const hub = getHub();
+    const parentAgent = hub.getAgent(requesterSessionId);
+    if (!parentAgent || parentAgent.closed) {
+      console.warn(
+        `[SubagentAnnounce] Parent agent not found or closed: ${requesterSessionId}`,
+      );
+      return false;
+    }
+
+    parentAgent.write(message);
+    return true;
+  } catch (err) {
+    console.error(`[SubagentAnnounce] Failed to announce to parent:`, err);
+    return false;
+  }
+}
--- a/src/agent/subagent/index.ts
+++ b/src/agent/subagent/index.ts
@ -0,0 +1,38 @@
+/**
+ * Subagent orchestration system.
+ *
+ * Provides child agent spawning, lifecycle management,
+ * persistent registry, and result announcement flow.
+ */
+
+export type {
+  SubagentRunOutcome,
+  SubagentRunRecord,
+  RegisterSubagentRunParams,
+  SubagentAnnounceParams,
+  SubagentSystemPromptParams,
+} from "./types.js";
+
+export {
+  initSubagentRegistry,
+  registerSubagentRun,
+  listSubagentRuns,
+  releaseSubagentRun,
+  getSubagentRun,
+  resetSubagentRegistryForTests,
+  shutdownSubagentRegistry,
+} from "./registry.js";
+
+export {
+  buildSubagentSystemPrompt,
+  readLatestAssistantReply,
+  formatAnnouncementMessage,
+  runSubagentAnnounceFlow,
+} from "./announce.js";
+export type { FormatAnnouncementParams } from "./announce.js";
+
+export {
+  loadSubagentRuns,
+  saveSubagentRuns,
+  getSubagentStorePath,
+} from "./registry-store.js";
--- a/src/agent/subagent/registry-store.test.ts
+++ b/src/agent/subagent/registry-store.test.ts
@ -0,0 +1,81 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import type { SubagentRunRecord } from "./types.js";
+
+// We need to test the store functions with a custom directory.
+// Since the store uses DATA_DIR from shared, we test the serialization logic directly.
+
+describe("registry-store serialization", () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), "subagent-store-test-"));
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it("round-trips SubagentRunRecord through JSON", () => {
+    const record: SubagentRunRecord = {
+      runId: "run-123",
+      childSessionId: "child-456",
+      requesterSessionId: "parent-789",
+      task: "Analyze code quality",
+      label: "Code Review",
+      cleanup: "delete",
+      createdAt: Date.now(),
+      startedAt: Date.now(),
+      endedAt: Date.now() + 30000,
+      outcome: { status: "ok" },
+      archiveAtMs: Date.now() + 3600000,
+      cleanupHandled: true,
+      cleanupCompletedAt: Date.now() + 30100,
+    };
+
+    // Serialize and deserialize
+    const json = JSON.stringify({ version: 1, runs: { "run-123": record } });
+    const parsed = JSON.parse(json);
+
+    expect(parsed.version).toBe(1);
+    expect(parsed.runs["run-123"]).toEqual(record);
+  });
+
+  it("handles record with minimal fields", () => {
+    const record: SubagentRunRecord = {
+      runId: "run-minimal",
+      childSessionId: "child-1",
+      requesterSessionId: "parent-1",
+      task: "Do something",
+      cleanup: "keep",
+      createdAt: Date.now(),
+    };
+
+    const json = JSON.stringify({ version: 1, runs: { "run-minimal": record } });
+    const parsed = JSON.parse(json);
+
+    expect(parsed.runs["run-minimal"].runId).toBe("run-minimal");
+    expect(parsed.runs["run-minimal"].outcome).toBeUndefined();
+    expect(parsed.runs["run-minimal"].label).toBeUndefined();
+  });
+
+  it("handles error outcome serialization", () => {
+    const record: SubagentRunRecord = {
+      runId: "run-err",
+      childSessionId: "child-err",
+      requesterSessionId: "parent-1",
+      task: "Fail",
+      cleanup: "delete",
+      createdAt: Date.now(),
+      outcome: { status: "error", error: "Something went wrong" },
+    };
+
+    const json = JSON.stringify(record);
+    const parsed = JSON.parse(json) as SubagentRunRecord;
+
+    expect(parsed.outcome?.status).toBe("error");
+    expect(parsed.outcome?.error).toBe("Something went wrong");
+  });
+});
--- a/src/agent/subagent/registry-store.ts
+++ b/src/agent/subagent/registry-store.ts
@ -0,0 +1,61 @@
+/**
+ * Persistent storage for subagent run records.
+ *
+ * File: ~/.super-multica/subagents/runs.json
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { DATA_DIR } from "../../shared/index.js";
+import type { SubagentRunRecord } from "./types.js";
+
+const SUBAGENTS_DIR = join(DATA_DIR, "subagents");
+const RUNS_FILE = join(SUBAGENTS_DIR, "runs.json");
+
+interface SubagentRunsStore {
+  version: 1;
+  runs: Record<string, SubagentRunRecord>;
+}
+
+function ensureDir(): void {
+  if (!existsSync(SUBAGENTS_DIR)) {
+    mkdirSync(SUBAGENTS_DIR, { recursive: true });
+  }
+}
+
+/** Get the path to the subagent store file (for testing) */
+export function getSubagentStorePath(): string {
+  return RUNS_FILE;
+}
+
+/** Load all persisted subagent runs */
+export function loadSubagentRuns(): Map<string, SubagentRunRecord> {
+  if (!existsSync(RUNS_FILE)) return new Map();
+
+  try {
+    const content = readFileSync(RUNS_FILE, "utf-8");
+    const store = JSON.parse(content) as SubagentRunsStore;
+
+    if (store.version !== 1) {
+      console.warn(`[SubagentStore] Unknown store version: ${store.version}, ignoring`);
+      return new Map();
+    }
+
+    return new Map(Object.entries(store.runs));
+  } catch (err) {
+    console.warn(`[SubagentStore] Failed to load runs:`, err);
+    return new Map();
+  }
+}
+
+/** Save all subagent runs to disk */
+export function saveSubagentRuns(runs: Map<string, SubagentRunRecord>): void {
+  ensureDir();
+
+  const store: SubagentRunsStore = {
+    version: 1,
+    runs: Object.fromEntries(runs),
+  };
+
+  writeFileSync(RUNS_FILE, JSON.stringify(store, null, 2), "utf-8");
+}
--- a/src/agent/subagent/registry.test.ts
+++ b/src/agent/subagent/registry.test.ts
@ -0,0 +1,161 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import {
+  registerSubagentRun,
+  listSubagentRuns,
+  getSubagentRun,
+  releaseSubagentRun,
+  resetSubagentRegistryForTests,
+  shutdownSubagentRegistry,
+} from "./registry.js";
+
+// Note: These tests exercise the registry's in-memory state management.
+// They do NOT test the full lifecycle (which requires a live Hub + AsyncAgent).
+
+beforeEach(() => {
+  resetSubagentRegistryForTests();
+});
+
+describe("subagent registry", () => {
+  it("registers a run and retrieves it by ID", () => {
+    const record = registerSubagentRun({
+      runId: "run-1",
+      childSessionId: "child-1",
+      requesterSessionId: "parent-1",
+      task: "Analyze code",
+      label: "Code Analysis",
+    });
+
+    expect(record.runId).toBe("run-1");
+    expect(record.childSessionId).toBe("child-1");
+    expect(record.requesterSessionId).toBe("parent-1");
+    expect(record.task).toBe("Analyze code");
+    expect(record.label).toBe("Code Analysis");
+    expect(record.cleanup).toBe("delete"); // default
+    expect(record.createdAt).toBeGreaterThan(0);
+    expect(record.startedAt).toBeGreaterThan(0); // set by watchChildAgent
+
+    const retrieved = getSubagentRun("run-1");
+    expect(retrieved).toBe(record);
+  });
+
+  it("lists runs filtered by requester session", () => {
+    registerSubagentRun({
+      runId: "run-1",
+      childSessionId: "child-1",
+      requesterSessionId: "parent-A",
+      task: "Task 1",
+    });
+    registerSubagentRun({
+      runId: "run-2",
+      childSessionId: "child-2",
+      requesterSessionId: "parent-B",
+      task: "Task 2",
+    });
+    registerSubagentRun({
+      runId: "run-3",
+      childSessionId: "child-3",
+      requesterSessionId: "parent-A",
+      task: "Task 3",
+    });
+
+    const parentARuns = listSubagentRuns("parent-A");
+    expect(parentARuns).toHaveLength(2);
+    expect(parentARuns.map((r) => r.runId).sort()).toEqual(["run-1", "run-3"]);
+
+    const parentBRuns = listSubagentRuns("parent-B");
+    expect(parentBRuns).toHaveLength(1);
+    expect(parentBRuns[0]!.runId).toBe("run-2");
+
+    const emptyRuns = listSubagentRuns("parent-C");
+    expect(emptyRuns).toHaveLength(0);
+  });
+
+  it("releases a run from the registry", () => {
+    registerSubagentRun({
+      runId: "run-1",
+      childSessionId: "child-1",
+      requesterSessionId: "parent-1",
+      task: "Task",
+    });
+
+    expect(getSubagentRun("run-1")).toBeDefined();
+
+    const released = releaseSubagentRun("run-1");
+    expect(released).toBe(true);
+    expect(getSubagentRun("run-1")).toBeUndefined();
+
+    // Double release returns false
+    const releasedAgain = releaseSubagentRun("run-1");
+    expect(releasedAgain).toBe(false);
+  });
+
+  it("applies custom cleanup value", () => {
+    const record = registerSubagentRun({
+      runId: "run-keep",
+      childSessionId: "child-1",
+      requesterSessionId: "parent-1",
+      task: "Keep session",
+      cleanup: "keep",
+    });
+
+    expect(record.cleanup).toBe("keep");
+  });
+
+  it("registers a run and ends it with error when Hub is not available", () => {
+    // Without Hub initialized, watchChildAgent detects missing Hub
+    // and immediately ends the run with an error
+    registerSubagentRun({
+      runId: "run-no-hub",
+      childSessionId: "child-1",
+      requesterSessionId: "parent-1",
+      task: "Running task",
+    });
+
+    const record = getSubagentRun("run-no-hub");
+    expect(record?.startedAt).toBeGreaterThan(0);
+    expect(record?.endedAt).toBeGreaterThan(0);
+    expect(record?.outcome?.status).toBe("error");
+    expect(record?.outcome?.error).toContain("Hub not initialized");
+  });
+
+  it("shutdownSubagentRegistry marks unfinished runs as ended", () => {
+    // Directly set up a record without going through watchChildAgent
+    // to simulate a run that is still active
+    registerSubagentRun({
+      runId: "run-active",
+      childSessionId: "child-1",
+      requesterSessionId: "parent-1",
+      task: "Running task",
+    });
+
+    // The above run already ended due to no Hub; reset its endedAt
+    // to simulate a truly active run
+    const record = getSubagentRun("run-active");
+    if (record) {
+      record.endedAt = undefined;
+      record.outcome = undefined;
+    }
+
+    shutdownSubagentRegistry();
+
+    const after = getSubagentRun("run-active");
+    expect(after?.endedAt).toBeGreaterThan(0);
+    expect(after?.outcome?.status).toBe("unknown");
+  });
+
+  it("resetSubagentRegistryForTests clears all state", () => {
+    registerSubagentRun({
+      runId: "run-1",
+      childSessionId: "child-1",
+      requesterSessionId: "parent-1",
+      task: "Task",
+    });
+
+    expect(listSubagentRuns("parent-1")).toHaveLength(1);
+
+    resetSubagentRegistryForTests();
+
+    expect(listSubagentRuns("parent-1")).toHaveLength(0);
+    expect(getSubagentRun("run-1")).toBeUndefined();
+  });
+});
--- a/src/agent/subagent/registry.ts
+++ b/src/agent/subagent/registry.ts
@ -0,0 +1,333 @@
+/**
+ * Subagent registry — in-memory tracking + lifecycle management.
+ *
+ * Tracks all active subagent runs, persists state to disk,
+ * watches for child completion, and triggers announce flow.
+ */
+
+import { getHub, isHubInitialized } from "../../hub/hub-singleton.js";
+import { loadSubagentRuns, saveSubagentRuns } from "./registry-store.js";
+import { runSubagentAnnounceFlow } from "./announce.js";
+import type {
+  RegisterSubagentRunParams,
+  SubagentRunRecord,
+} from "./types.js";
+import { resolveSessionDir } from "../session/storage.js";
+import { rmSync } from "node:fs";
+
+/** Default archive retention: 60 minutes after completion */
+const DEFAULT_ARCHIVE_AFTER_MS = 60 * 60 * 1000;
+
+/** Archive sweep interval: 60 seconds */
+const SWEEP_INTERVAL_MS = 60 * 1000;
+
+// ============================================================================
+// Module-level state
+// ============================================================================
+
+const subagentRuns = new Map<string, SubagentRunRecord>();
+let sweepTimer: ReturnType<typeof setInterval> | undefined;
+const resumedRuns = new Set<string>();
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+/** Initialize registry from persisted state. Call once at startup. */
+export function initSubagentRegistry(): void {
+  const persisted = loadSubagentRuns();
+  for (const [runId, record] of persisted) {
+    subagentRuns.set(runId, record);
+
+    // Resume incomplete runs
+    if (!record.cleanupHandled) {
+      if (record.endedAt) {
+        // Completed but cleanup not done — run announce flow
+        if (!resumedRuns.has(runId)) {
+          resumedRuns.add(runId);
+          handleRunCompletion(record);
+        }
+      } else {
+        // If not ended, the child agent session is lost on restart —
+        // mark as ended with unknown outcome
+        record.endedAt = Date.now();
+        record.outcome = { status: "unknown" };
+        persist();
+        if (!resumedRuns.has(runId)) {
+          resumedRuns.add(runId);
+          handleRunCompletion(record);
+        }
+      }
+    }
+  }
+
+  if (subagentRuns.size > 0) {
+    startSweeper();
+    console.log(`[SubagentRegistry] Loaded ${subagentRuns.size} persisted run(s)`);
+  }
+}
+
+/** Register a new subagent run and start tracking its lifecycle. */
+export function registerSubagentRun(params: RegisterSubagentRunParams): SubagentRunRecord {
+  const {
+    runId,
+    childSessionId,
+    requesterSessionId,
+    task,
+    label,
+    cleanup = "delete",
+    timeoutSeconds,
+  } = params;
+
+  const record: SubagentRunRecord = {
+    runId,
+    childSessionId,
+    requesterSessionId,
+    task,
+    label,
+    cleanup,
+    createdAt: Date.now(),
+  };
+
+  subagentRuns.set(runId, record);
+  persist();
+  startSweeper();
+
+  // Start watching the child agent for completion
+  watchChildAgent(record, timeoutSeconds);
+
+  return record;
+}
+
+/** List all active runs for a given requester session. */
+export function listSubagentRuns(requesterSessionId: string): SubagentRunRecord[] {
+  const result: SubagentRunRecord[] = [];
+  for (const record of subagentRuns.values()) {
+    if (record.requesterSessionId === requesterSessionId) {
+      result.push(record);
+    }
+  }
+  return result;
+}
+
+/** Remove a run from the registry. */
+export function releaseSubagentRun(runId: string): boolean {
+  const deleted = subagentRuns.delete(runId);
+  if (deleted) {
+    persist();
+    if (subagentRuns.size === 0) {
+      stopSweeper();
+    }
+  }
+  return deleted;
+}
+
+/** Get a run by ID. */
+export function getSubagentRun(runId: string): SubagentRunRecord | undefined {
+  return subagentRuns.get(runId);
+}
+
+/** Mark all active (non-ended) runs as ended with "unknown" status. Called during Hub shutdown. */
+export function shutdownSubagentRegistry(): void {
+  const now = Date.now();
+  let updated = 0;
+
+  for (const record of subagentRuns.values()) {
+    if (!record.endedAt) {
+      record.endedAt = now;
+      record.outcome = { status: "unknown" };
+      updated++;
+    }
+  }
+
+  if (updated > 0) {
+    persist();
+    console.log(`[SubagentRegistry] Marked ${updated} active run(s) as ended during shutdown`);
+  }
+
+  stopSweeper();
+}
+
+/** Reset all state (for testing). */
+export function resetSubagentRegistryForTests(): void {
+  subagentRuns.clear();
+  resumedRuns.clear();
+  stopSweeper();
+}
+
+// ============================================================================
+// Lifecycle watching
+// ============================================================================
+
+function watchChildAgent(record: SubagentRunRecord, timeoutSeconds?: number): void {
+  const { childSessionId } = record;
+
+  // Mark as started
+  record.startedAt = Date.now();
+  persist();
+
+  const cleanup = (outcome: { status: "ok" | "error" | "timeout" | "unknown"; error?: string | undefined }) => {
+    if (record.endedAt) return; // Already finalized
+    if (timeoutTimer) clearTimeout(timeoutTimer);
+    record.endedAt = Date.now();
+    record.outcome = outcome;
+    persist();
+    handleRunCompletion(record);
+  };
+
+  // Set up timeout if specified
+  let timeoutTimer: ReturnType<typeof setTimeout> | undefined;
+  if (timeoutSeconds && timeoutSeconds > 0) {
+    timeoutTimer = setTimeout(() => {
+      cleanup({ status: "timeout" });
+
+      // Try to close the child agent
+      try {
+        const hub = getHub();
+        hub.closeAgent(childSessionId);
+      } catch {
+        // Hub may not be available
+      }
+    }, timeoutSeconds * 1000);
+  }
+
+  // Get child agent reference (Hub may not be available in tests)
+  if (!isHubInitialized()) {
+    cleanup({ status: "error", error: "Hub not initialized" });
+    return;
+  }
+
+  const hub = getHub();
+  const childAgent = hub.getAgent(childSessionId);
+  if (!childAgent) {
+    cleanup({ status: "error", error: "Child agent not found" });
+    return;
+  }
+
+  // Wait for the child agent's task queue to drain (task completion),
+  // then trigger announce flow. Uses waitForIdle() instead of consuming
+  // the stream (which would conflict with Hub.consumeAgent).
+  childAgent.waitForIdle().then(
+    () => cleanup({ status: "ok" }),
+    (err) => cleanup({
+      status: "error",
+      error: err instanceof Error ? err.message : String(err),
+    }),
+  );
+
+  // Also handle explicit close (e.g., timeout kill, Hub shutdown)
+  childAgent.onClose(() => {
+    cleanup({ status: record.outcome?.status ?? "unknown" });
+  });
+}
+
+// ============================================================================
+// Cleanup + Announce
+// ============================================================================
+
+function handleRunCompletion(record: SubagentRunRecord): void {
+  if (record.cleanupHandled) return;
+  record.cleanupHandled = true;
+  persist();
+
+  // Run announce flow
+  const announced = runSubagentAnnounceFlow({
+    runId: record.runId,
+    childSessionId: record.childSessionId,
+    requesterSessionId: record.requesterSessionId,
+    task: record.task,
+    label: record.label,
+    cleanup: record.cleanup,
+    outcome: record.outcome,
+    startedAt: record.startedAt,
+    endedAt: record.endedAt,
+  });
+
+  if (!announced) {
+    console.warn(`[SubagentRegistry] Announce flow failed for run ${record.runId}`);
+    // Allow retry on next restart if announce failed.
+    record.cleanupHandled = false;
+    persist();
+    return;
+  }
+
+  // Handle session cleanup
+  if (record.cleanup === "delete") {
+    deleteChildSession(record.childSessionId);
+  }
+
+  // Schedule archive
+  record.archiveAtMs = Date.now() + DEFAULT_ARCHIVE_AFTER_MS;
+  record.cleanupCompletedAt = Date.now();
+  persist();
+}
+
+function deleteChildSession(sessionId: string): void {
+  try {
+    const sessionDir = resolveSessionDir(sessionId);
+    rmSync(sessionDir, { recursive: true, force: true });
+    console.log(`[SubagentRegistry] Deleted child session: ${sessionId}`);
+  } catch (err) {
+    console.warn(`[SubagentRegistry] Failed to delete child session ${sessionId}:`, err);
+  }
+
+  // Also close the agent in Hub
+  try {
+    const hub = getHub();
+    hub.closeAgent(sessionId);
+  } catch {
+    // Hub may not be available
+  }
+}
+
+// ============================================================================
+// Archive sweeper
+// ============================================================================
+
+function startSweeper(): void {
+  if (sweepTimer) return;
+  sweepTimer = setInterval(sweep, SWEEP_INTERVAL_MS);
+  // Don't prevent process exit
+  if (sweepTimer.unref) sweepTimer.unref();
+}
+
+function stopSweeper(): void {
+  if (sweepTimer) {
+    clearInterval(sweepTimer);
+    sweepTimer = undefined;
+  }
+}
+
+function sweep(): void {
+  const now = Date.now();
+  let removed = 0;
+
+  for (const [runId, record] of subagentRuns) {
+    if (record.archiveAtMs !== undefined && record.archiveAtMs <= now) {
+      subagentRuns.delete(runId);
+      resumedRuns.delete(runId);
+      removed++;
+    }
+  }
+
+  if (removed > 0) {
+    persist();
+    console.log(`[SubagentRegistry] Archived ${removed} completed run(s)`);
+  }
+
+  if (subagentRuns.size === 0) {
+    stopSweeper();
+  }
+}
+
+// ============================================================================
+// Persistence helper
+// ============================================================================
+
+function persist(): void {
+  try {
+    saveSubagentRuns(subagentRuns);
+  } catch (err) {
+    console.error(`[SubagentRegistry] Failed to persist runs:`, err);
+  }
+}
--- a/src/agent/subagent/types.ts
+++ b/src/agent/subagent/types.ts
@ -0,0 +1,74 @@
+/**
+ * Subagent orchestration types.
+ *
+ * Models the lifecycle of spawned child agents:
+ * created → started → ended → cleanup
+ */
+
+/** Final outcome of a subagent run */
+export type SubagentRunOutcome = {
+  status: "ok" | "error" | "timeout" | "unknown";
+  error?: string | undefined;
+};
+
+/** Persistent record tracking a single subagent run */
+export type SubagentRunRecord = {
+  /** Unique run identifier (UUIDv7) */
+  runId: string;
+  /** Session ID of the child agent */
+  childSessionId: string;
+  /** Session ID of the parent (requester) agent */
+  requesterSessionId: string;
+  /** The task description / prompt given to the child */
+  task: string;
+  /** Optional human-readable label */
+  label?: string | undefined;
+  /** Session cleanup strategy after completion */
+  cleanup: "delete" | "keep";
+  /** Timestamp when the run was created */
+  createdAt: number;
+  /** Timestamp when the child agent started execution */
+  startedAt?: number | undefined;
+  /** Timestamp when the child agent finished */
+  endedAt?: number | undefined;
+  /** Final status of the run */
+  outcome?: SubagentRunOutcome | undefined;
+  /** Scheduled auto-archive time (ms since epoch) */
+  archiveAtMs?: number | undefined;
+  /** Whether the cleanup/announce flow has been initiated */
+  cleanupHandled?: boolean | undefined;
+  /** Timestamp when cleanup completed */
+  cleanupCompletedAt?: number | undefined;
+};
+
+/** Parameters for registering a new subagent run */
+export type RegisterSubagentRunParams = {
+  runId: string;
+  childSessionId: string;
+  requesterSessionId: string;
+  task: string;
+  label?: string | undefined;
+  cleanup?: "delete" | "keep" | undefined;
+  timeoutSeconds?: number | undefined;
+};
+
+/** Parameters for the announce flow */
+export type SubagentAnnounceParams = {
+  runId: string;
+  childSessionId: string;
+  requesterSessionId: string;
+  task: string;
+  label?: string | undefined;
+  cleanup: "delete" | "keep";
+  outcome?: SubagentRunOutcome | undefined;
+  startedAt?: number | undefined;
+  endedAt?: number | undefined;
+};
+
+/** Parameters for building the subagent system prompt */
+export type SubagentSystemPromptParams = {
+  requesterSessionId: string;
+  childSessionId: string;
+  label?: string | undefined;
+  task: string;
+};
--- a/src/agent/tools.ts
+++ b/src/agent/tools.ts
@ -6,6 +6,7 @@ import { createProcessTool } from "./tools/process.js";
 import { createGlobTool } from "./tools/glob.js";
 import { createWebFetchTool, createWebSearchTool } from "./tools/web/index.js";
 import { createMemoryTools } from "./tools/memory/index.js";
+import { createSessionsSpawnTool } from "./tools/sessions-spawn.js";
 import { filterTools } from "./tools/policy.js";
 import { isMulticaError, isRetryableError } from "../shared/errors.js";

@ -19,6 +20,10 @@ export interface CreateToolsOptions {
  profileId?: string | undefined;
  /** Base directory for profiles (optional) */
  profileBaseDir?: string | undefined;
+  /** Whether this agent is a subagent (passed to sessions_spawn tool) */
+  isSubagent?: boolean | undefined;
+  /** Session ID of the agent (passed to sessions_spawn tool) */
+  sessionId?: string | undefined;
 }

 type ToolErrorPayload = {
@ -88,7 +93,7 @@ function wrapTool<TParams, TResult>(
 export function createAllTools(options: CreateToolsOptions | string): AgentTool<any>[] {
  // Support legacy string argument for backwards compatibility
  const opts: CreateToolsOptions = typeof options === "string" ? { cwd: options } : options;
-  const { cwd, profileId, profileBaseDir } = opts;
+  const { cwd, profileId, profileBaseDir, isSubagent, sessionId } = opts;

  const baseTools = createCodingTools(cwd).filter(
    (tool) => tool.name !== "bash",
@ -118,6 +123,13 @@ export function createAllTools(options: CreateToolsOptions | string): AgentTool<
    tools.push(...memoryTools);
  }

+  // Add sessions_spawn tool (will be filtered by policy for subagents)
+  const sessionsSpawnTool = createSessionsSpawnTool({
+    isSubagent: isSubagent ?? false,
+    sessionId,
+  });
+  tools.push(sessionsSpawnTool as AgentTool<any>);
+
  return tools;
 }

@ -138,6 +150,8 @@ export function resolveTools(options: AgentOptions): AgentTool<any>[] {
    cwd,
    profileId: options.profileId,
    profileBaseDir: options.profileBaseDir,
+    isSubagent: options.isSubagent,
+    sessionId: options.sessionId,
  });

  // Apply policy filtering
--- a/src/agent/tools/groups.ts
+++ b/src/agent/tools/groups.ts
@ -35,6 +35,9 @@ export const TOOL_GROUPS: Record<string, string[]> = {
  // Memory tools (requires profileId)
  "group:memory": ["memory_get", "memory_set", "memory_delete", "memory_list"],

+  // Subagent tools
+  "group:subagent": ["sessions_spawn"],
+
  // All core tools
  "group:core": [
    "read",
@ -76,16 +79,8 @@ export const TOOL_PROFILES: Record<ToolProfileId, { allow?: string[]; deny?: str
 * Subagents should not have access to session management or system tools.
 */
 export const DEFAULT_SUBAGENT_TOOL_DENY: string[] = [
-  // Future: session management tools
-  // "sessions_list",
-  // "sessions_history",
-  // "sessions_send",
-  // "sessions_spawn",
-  // "session_status",
-
-  // Future: system tools
-  // "gateway",
-  // "agents_list",
+  // Subagents cannot spawn subagents (no nested spawning)
+  "sessions_spawn",
 ];

 /**
--- a/src/agent/tools/sessions-spawn.test.ts
+++ b/src/agent/tools/sessions-spawn.test.ts
@ -0,0 +1,40 @@
+import { describe, it, expect } from "vitest";
+import { createSessionsSpawnTool } from "./sessions-spawn.js";
+
+describe("sessions_spawn tool", () => {
+  it("has correct name and description", () => {
+    const tool = createSessionsSpawnTool({ isSubagent: false, sessionId: "test-session" });
+    expect(tool.name).toBe("sessions_spawn");
+    expect(tool.label).toBe("Spawn Subagent");
+    expect(tool.description).toContain("Spawn a background subagent");
+  });
+
+  it("rejects spawn from subagent sessions", async () => {
+    const tool = createSessionsSpawnTool({ isSubagent: true, sessionId: "child-session" });
+
+    const result = await tool.execute(
+      "call-1",
+      { task: "do something" } as any,
+      new AbortController().signal,
+    );
+
+    expect(result.details.status).toBe("error");
+    expect(result.details.error).toContain("not allowed from sub-agent sessions");
+    const firstContent = result.content[0] as { type: string; text: string };
+    expect(firstContent.text).toContain("not allowed");
+  });
+
+  it("fails gracefully when Hub is not initialized", async () => {
+    const tool = createSessionsSpawnTool({ isSubagent: false, sessionId: "parent-session" });
+
+    const result = await tool.execute(
+      "call-2",
+      { task: "analyze code", label: "Code Analysis" } as any,
+      new AbortController().signal,
+    );
+
+    // Should get an error because Hub singleton is not set up in test
+    expect(result.details.status).toBe("error");
+    expect(result.details.error).toContain("Hub");
+  });
+});
--- a/src/agent/tools/sessions-spawn.ts
+++ b/src/agent/tools/sessions-spawn.ts
@ -0,0 +1,143 @@
+/**
+ * sessions_spawn tool — allows a parent agent to spawn subagent runs.
+ *
+ * Subagents run in isolated sessions with restricted tools.
+ * Results are announced back to the parent when the child completes.
+ */
+
+import { v7 as uuidv7 } from "uuid";
+import { Type } from "@sinclair/typebox";
+import type { AgentTool } from "@mariozechner/pi-agent-core";
+import { getHub } from "../../hub/hub-singleton.js";
+import { buildSubagentSystemPrompt } from "../subagent/announce.js";
+import { registerSubagentRun } from "../subagent/registry.js";
+
+const SessionsSpawnSchema = Type.Object({
+  task: Type.String({ description: "The task for the subagent to perform.", minLength: 1 }),
+  label: Type.Optional(
+    Type.String({ description: "Human-readable label for this background task." }),
+  ),
+  model: Type.Optional(
+    Type.String({ description: "Override the LLM model for the subagent (e.g. 'gpt-4o', 'claude-sonnet')." }),
+  ),
+  cleanup: Type.Optional(
+    Type.Union([Type.Literal("delete"), Type.Literal("keep")], {
+      description: "Session cleanup after completion. 'delete' removes session files, 'keep' preserves for audit. Default: 'delete'.",
+    }),
+  ),
+  timeoutSeconds: Type.Optional(
+    Type.Number({
+      description: "Execution timeout in seconds. The subagent will be terminated if it exceeds this.",
+      minimum: 1,
+    }),
+  ),
+});
+
+type SessionsSpawnArgs = {
+  task: string;
+  label?: string;
+  model?: string;
+  cleanup?: "delete" | "keep";
+  timeoutSeconds?: number;
+};
+
+export type SessionsSpawnResult = {
+  status: "accepted" | "error";
+  childSessionId?: string;
+  runId?: string;
+  error?: string;
+};
+
+export interface CreateSessionsSpawnToolOptions {
+  /** Whether the current agent is itself a subagent */
+  isSubagent?: boolean;
+  /** Session ID of the current (requester) agent */
+  sessionId?: string;
+}
+
+export function createSessionsSpawnTool(
+  options: CreateSessionsSpawnToolOptions,
+): AgentTool<typeof SessionsSpawnSchema, SessionsSpawnResult> {
+  return {
+    name: "sessions_spawn",
+    label: "Spawn Subagent",
+    description:
+      "Spawn a background subagent to handle a specific task. The subagent runs in an isolated session with its own tool set. " +
+      "When it completes, its findings are announced back to you automatically. " +
+      "Use this for parallelizable work, long-running analysis, or tasks that benefit from isolation.",
+    parameters: SessionsSpawnSchema,
+    execute: async (_toolCallId, args) => {
+      const { task, label, model, cleanup = "delete", timeoutSeconds } = args as SessionsSpawnArgs;
+
+      // Guard: subagents cannot spawn subagents
+      if (options.isSubagent) {
+        return {
+          content: [{ type: "text", text: "Error: sessions_spawn is not allowed from sub-agent sessions." }],
+          details: {
+            status: "error",
+            error: "sessions_spawn is not allowed from sub-agent sessions",
+          },
+        };
+      }
+
+      const requesterSessionId = options.sessionId ?? "unknown";
+      const runId = uuidv7();
+      const childSessionId = uuidv7();
+
+      // Build system prompt for the child
+      const systemPrompt = buildSubagentSystemPrompt({
+        requesterSessionId,
+        childSessionId,
+        label,
+        task,
+      });
+
+      // Spawn child agent via Hub
+      try {
+        const hub = getHub();
+        const childAgent = hub.createSubagent(childSessionId, {
+          systemPrompt,
+          model,
+        });
+
+        // Write the task to the child (non-blocking) before registering,
+        // so waitForIdle() observes the queued work.
+        childAgent.write(task);
+
+        // Register the run for lifecycle tracking
+        registerSubagentRun({
+          runId,
+          childSessionId,
+          requesterSessionId,
+          task,
+          label,
+          cleanup,
+          timeoutSeconds,
+        });
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Subagent spawned successfully.\n\nRun ID: ${runId}\nSession: ${childSessionId}\nTask: ${label || task.slice(0, 80)}\n\nThe subagent is now working in the background. You will receive its findings when it completes.`,
+            },
+          ],
+          details: {
+            status: "accepted",
+            childSessionId,
+            runId,
+          },
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{ type: "text", text: `Error spawning subagent: ${message}` }],
+          details: {
+            status: "error",
+            error: message,
+          },
+        };
+      }
+    },
+  };
+}
--- a/src/hub/hub-singleton.ts
+++ b/src/hub/hub-singleton.ts
@ -0,0 +1,28 @@
+/**
+ * Global Hub singleton for cross-module access.
+ *
+ * Used by subagent tools and announce flow to interact with the Hub
+ * without threading references through the entire call chain.
+ */
+
+import type { Hub } from "./hub.js";
+
+let _hub: Hub | undefined;
+
+/** Set the global Hub instance. Called once during Hub construction. */
+export function setHub(hub: Hub): void {
+  _hub = hub;
+}
+
+/** Get the global Hub instance. Throws if not yet initialized. */
+export function getHub(): Hub {
+  if (!_hub) {
+    throw new Error("[Hub] Hub singleton not initialized. Ensure Hub is constructed before accessing.");
+  }
+  return _hub;
+}
+
+/** Check if the Hub singleton has been initialized. */
+export function isHubInitialized(): boolean {
+  return _hub !== undefined;
+}
--- a/src/hub/hub.ts
+++ b/src/hub/hub.ts
@ -9,7 +9,10 @@ import {
  type ResponseErrorPayload,
 } from "@multica/sdk";
 import { AsyncAgent } from "../agent/async-agent.js";
+import type { AgentOptions } from "../agent/types.js";
 import { getHubId } from "./hub-identity.js";
+import { setHub } from "./hub-singleton.js";
+import { initSubagentRegistry, shutdownSubagentRegistry } from "../agent/subagent/index.js";
 import { loadAgentRecords, addAgentRecord, removeAgentRecord } from "./agent-store.js";
 import { RpcDispatcher, RpcError } from "./rpc/dispatcher.js";
 import { createGetAgentMessagesHandler } from "./rpc/handlers/get-agent-messages.js";
@ -48,6 +51,12 @@ export class Hub {
    this.rpc.register("deleteAgent", createDeleteAgentHandler(this));
    this.rpc.register("updateGateway", createUpdateGatewayHandler(this));

+    // Register as global singleton for cross-module access (subagent tools, announce flow)
+    setHub(this);
+
+    // Restore subagent registry from persistent state
+    initSubagentRegistry();
+
    this.client = this.createClient(this.url);
    this.client.connect();
    this.restoreAgents();
@ -243,6 +252,27 @@ export class Hub {
    }
  }

+  /** Create a subagent with specific options (isSubagent, systemPrompt, model) */
+  createSubagent(sessionId: string, options: Omit<AgentOptions, "sessionId"> = {}): AsyncAgent {
+    const existing = this.agents.get(sessionId);
+    if (existing && !existing.closed) {
+      return existing;
+    }
+
+    const agent = new AsyncAgent({
+      ...options,
+      sessionId,
+      isSubagent: true,
+    });
+    this.agents.set(agent.sessionId, agent);
+
+    // Subagents are ephemeral — don't persist to agent store
+    void this.consumeAgent(agent);
+
+    console.log(`[Hub] Subagent created: ${agent.sessionId}`);
+    return agent;
+  }
+
  getAgent(id: string): AsyncAgent | undefined {
    return this.agents.get(id);
  }
@ -266,6 +296,9 @@ export class Hub {
  }

  shutdown(): void {
+    // Finalize subagent registry before closing agents
+    shutdownSubagentRegistry();
+
    for (const [id, agent] of this.agents) {
      agent.close();
      this.agents.delete(id);
				`@ -0,0 +1 @@`
				`{ "recommendations": ["expo.vscode-expo-tools"] }`