Conception de la capacité universelle Worktree

{racine du dépôt git}/.qwen/worktrees/{slug}

name?: string  // optionnel, format slug : lettres/chiffres/point/tiret bas/tiret, max 64 caractères

action: 'keep' | 'remove'
discard_changes?: boolean  // valide uniquement si action='remove'
**

**Garde de sécurité :**

- Opère uniquement sur le worktree créé par `EnterWorktree` dans cette session
- Si `action='remove'` et qu'il existe des modifications non commitées, l'exécution est refusée (sauf si `discard_changes: true`)

**Comportement :**

- `keep` : vide l'état worktree de la session, conserve le répertoire et la branche du worktree, restaure le répertoire de travail d'origine
- `remove` : supprime le répertoire du worktree, supprime la branche git correspondante, vide l'état de la session, restaure le répertoire de travail d'origine

**Sortie :** `action`, `originalCwd`, `worktreePath`, `worktreeBranch`

## Modes de déclenchement utilisateur

| Mode               | Exemple                                                             | Phase de mise en œuvre |
| ------------------ | ------------------------------------------------------------------- | ---------------------- |
| Demande explicite dans la session | L'utilisateur dit "commencer à travailler dans un worktree" → le modèle appelle `EnterWorktree` | Phase A |
| Isolation d'agent  | Le modèle définit `isolation: 'worktree'` pour un sous-agent        | Phase B                |
| Indicateur CLI     | `qwen --worktree my-feature`                                        | Phase D                |

Pas de commande slash. Le déclenchement du worktree dans la session dépend d'une mention explicite de l'utilisateur ; `isolation: 'worktree'` est le seul scénario où le modèle prend la décision de manière autonome.

## Plan de mise en œuvre par phases

### Phase A : Outils principaux (worktree au niveau session utilisateur)

**Objectif :** L'utilisateur peut entrer/sortir d'un worktree dans une session.

**Fonctionnalités à implémenter :**

- Outil `EnterWorktree` : crée le worktree, bascule le répertoire de travail, enregistre l'état de session
- Outil `ExitWorktree` : deux modes de sortie (keep / remove), garde de sécurité
- Extension de `GitWorktreeService` : nouvelles méthodes `createUserWorktree()` / `removeUserWorktree()` orientées session utilisateur unique, réutilisant la logique git existante, sans modifier les interfaces batch utilisées par Arena
- Extension de `SessionService` : nouveau champ `WorktreeSession`, enregistrant `{ slug, worktreePath, worktreeBranch, originalCwd, originalBranch }` ; restaure le répertoire de travail worktree lors du `--resume`
- Prompt des outils : rédiger des instructions d'utilisation pour chaque outil, précisant clairement quand appeler et quand ne pas appeler

**Fichiers impactés :**

| Fichier                                              | Type de modification                         |
| ---------------------------------------------------- | -------------------------------------------- |
| `packages/core/src/tools/tool-names.ts`              | Ajout des constantes `ENTER_WORKTREE`, `EXIT_WORKTREE` |
| `packages/core/src/tools/EnterWorktreeTool/`         | Nouveaux dossiers : `EnterWorktreeTool.ts`, `prompt.ts` |
| `packages/core/src/tools/ExitWorktreeTool/`          | Nouveaux dossiers : `ExitWorktreeTool.ts`, `prompt.ts` |
| `packages/core/src/services/gitWorktreeService.ts`   | Ajout de l'interface niveau session utilisateur (sans modifier l'interface Arena) |
| `packages/core/src/services/sessionService.ts`       | Ajout du champ `WorktreeSession` et des méthodes de lecture/écriture |
| `packages/core/src/tools/` point d'enregistrement    | Enregistrement des nouveaux outils           |

**Hors périmètre de la Phase A :**

- Isolation d'agent (Phase B)
- Configuration post-création comme hooks (Phase C)
- Affichage de l'état UI (Phase C)

---

### Phase B : Isolation d'agent (`AgentTool isolation: 'worktree'`) + mise à jour des descriptions

**Objectif :** Le modèle peut créer un worktree temporaire isolé pour un sous-agent, qui est automatiquement nettoyé après la fin de l'agent ; mise à jour simultanée des descriptions d'outils et des prompts impactés.

**Fonctionnalités à implémenter :**

_Cœur de l'isolation d'agent :_

- `AgentTool` ajoute le paramètre `isolation?: 'worktree'`
- Au démarrage de l'agent, crée un worktree temporaire (slug : `agent-{7hex}`, chemin : `.qwen/worktrees/agent-{7hex}`)
- Après la fin de l'agent : s'il n'y a pas de modification, suppression automatique ; s'il y a des modifications, conservation, retour du chemin et de la branche dans le résultat
- Nettoyage automatique des worktrees obsolètes : scanne `.qwen/worktrees/`, repère les motifs `agent-{7hex}`, supprime ceux de plus de 30 jours sans commit non poussé, stratégie fail-closed

_Mise à jour des descriptions et prompts :_

- La description d'`AgentTool` complète la documentation du paramètre `isolation: 'worktree'` (référence : `AgentTool/prompt.ts:272` de claude-code)
- Nouveau `buildWorktreeNotice()` : lorsqu'un sous-agent forké s'exécute dans un worktree, injecte un contexte indiquant qu'il est dans un worktree isolé, que le chemin est hérité de l'agent parent, et qu'il faut re-lire les fichiers avant de modifier (référence : `forkSubagent.ts:buildWorktreeNotice` de claude-code)

_Aucune modification nécessaire :_

- review skill (`SKILL.md`) : review utilise un mécanisme indépendant (chemin `.qwen/tmp/review-pr-<n>`, créé via la commande `qwen review fetch-pr`), totalement différent du chemin et du mécanisme universel du worktree ; pas de confusion possible

**Garantie de compatibilité Arena :** Arena ne passe pas par le paramètre `isolation` pour créer des worktrees ; cette modification ne touche pas au code d'Arena.

**Fichiers impactés :**

| Fichier                                              | Type de modification                         |
| ---------------------------------------------------- | -------------------------------------------- |
| `packages/core/src/tools/agent/agent.ts`             | Ajout du paramètre `isolation` et de la logique de création/nettoyage du worktree |
| `packages/core/src/tools/agent/fork-subagent.ts`     | Ajout de `buildWorktreeNotice()` et injection en mode worktree |
| `packages/core/src/services/gitWorktreeService.ts`   | Ajout de `createAgentWorktree()` / `removeAgentWorktree()` |
| `packages/core/src/services/worktreeCleanup.ts`      | Nouveau fichier : logique de nettoyage automatique des worktrees obsolètes |

---

### Phase C : Intégrité de session (persistance SessionService + filet de sécurité UI)

**Objectif :** L'état du worktree peut être restauré après une interruption de session ; l'utilisateur sait toujours dans quel worktree il se trouve via l'interface ; une invite de sécurité s'affiche lors de la sortie de session.

**Fonctionnalités à implémenter :**

_Persistance de l'état worktree dans SessionService + restauration `--resume` :_

- `SessionService` étend le champ `WorktreeSession`, enregistre `{ slug, worktreePath, worktreeBranch, originalCwd, originalBranch }`
- `EnterWorktreeTool` appelle `sessionService.setWorktreeSession()` pour écrire l'état
- `ExitWorktreeTool` appelle `sessionService.clearWorktreeSession()` pour effacer l'état
- Le chemin de démarrage `--resume` lit ce champ, restaure `targetDir` et injecte un contexte d'information au modèle

_Configuration post-création :_

- Après la création du worktree, exécute automatiquement `git config core.hooksPath <mainRepo>/.git/hooks` pour garantir que les commits dans le worktree respectent le comportement des hooks du dépôt principal

_Affichage worktree dans StatusLine :_

- `UIStateContext` ajoute un champ `activeWorktree` (lu depuis l'état de session), mis à jour lors de l'entrée/sortie du worktree
- Le payload `StatusLineCommandInput` ajoute un champ `worktree?: { slug: string; branch: string }` destiné aux scripts de statusline utilisateur
- Le `Footer` affiche intégré une ligne `⎇ <branch> (<slug>)` lorsque `activeWorktree` n'est pas vide, sans nécessiter de configuration de script statusline pour une visibilité de base

_WorktreeExitDialog :_

- Nouveau composant `WorktreeExitDialog.tsx`, reprenant la structure existante des Dialog
- Modification de la gestion des touches de sortie (Ctrl+C / Ctrl+D) : détecte si `activeWorktree` n'est pas vide, intercepte une deuxième confirmation, affiche la Dialog pour demander à l'utilisateur de choisir keep ou remove
- Les actions keep/remove réutilisent les chemins existants de `ExitWorktreeTool`

**Fichiers impactés :**

| Fichier                                                         | Type de modification                                                                 |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `packages/core/src/services/sessionService.ts`                  | Ajout du champ `WorktreeSession` et des méthodes de lecture/écriture                 |
| `packages/core/src/tools/enter-worktree.ts`                     | Appel à `sessionService.setWorktreeSession()`                                       |
| `packages/core/src/tools/exit-worktree.ts`                      | Appel à `sessionService.clearWorktreeSession()`                                     |
| `packages/core/src/services/gitWorktreeService.ts`              | Ajout de la configuration `core.hooksPath` après `createUserWorktree()` / `createAgentWorktree()` |
| `packages/cli/src/ui/contexts/UIStateContext.tsx`                | Ajout du champ `activeWorktree` et des actions set/clear                             |
| `packages/cli/src/ui/hooks/useStatusLine.ts`                    | Ajout du champ `worktree` dans `StatusLineCommandInput`                              |
| `packages/cli/src/ui/components/Footer.tsx`                     | Affichage intégré de la ligne worktree                                               |
| `packages/cli/src/ui/components/WorktreeExitDialog.tsx`         | Nouveau fichier                                                                      |
| `packages/cli/src/ui/components/DialogManager.tsx`              | Enregistrement de `WorktreeExitDialog`                                               |
| `packages/cli/src/ui/components/ExitWarning.tsx` ou gestion des touches de sortie | Détection de `activeWorktree` et interception de la sortie          |

---

### Phase D : Configuration au démarrage (indicateur CLI `--worktree` + liens symboliques de répertoires + référence PR)

**Objectif :** Prendre en charge l'entrée directe dans un worktree au démarrage, réduire la consommation de disque pour les grands projets via des liens symboliques de répertoires, et créer rapidement un worktree basé sur une pull request via une référence PR.

**Périmètre :** Les trois fonctionnalités sont mises en œuvre ensemble dans une même phase car elles sont toutes accrochées au même point d'entrée de démarrage, et les liens symboliques / le fetch PR doivent être exécutés immédiatement après la création du worktree — les diviser nécessiterait de modifier deux fois la séquence de bootstrap.

#### D-1 : Indicateur CLI `--worktree [name]`

**Forme du paramètre :** L'option yargs accepte trois formes :

| Forme                      | Comportement                                                    |
| -------------------------- | --------------------------------------------------------------- |
| `qwen --worktree`          | bare flag, génération automatique du slug (`{adjectif}-{nom}-{6hex}`) |
| `qwen --worktree mon-nom`  | slug explicite, reprend les règles de validation de slug de `EnterWorktreeTool` |
| `qwen --worktree=mon-nom`  | équivalent à la forme précédente                               |

Pas d'alias court `-w` (les alias courts de qwen-code sont réservés aux paramètres les plus fréquents pour éviter les conflits de noms).

**Séquence de démarrage :** Le worktree est créé à l'emplacement suivant :

1. `parseArguments()` analyse argv (existant)
2. resume picker (existant, lignes 588-629 de `gemini.tsx`)
3. `loadCliConfig()` initialise Config + auth (existant, lignes 643-653)
4. **Nouveau :** si `argv.worktree !== undefined`, appelle `createUserWorktree()`
   - Écrit un sidecar (`writeWorktreeSession()`)
   - Définit `process.chdir(worktreePath)` et `Config.setTargetDir(worktreePath)`
   - Chemin de re-attachement au même worktree : saute `git worktree add` et fait un chdir sur place (correction Phase 6). La combinaison `--resume` × `--worktree` avec des projectHash différents échouera lors de la recherche de session, voir la priorité avec `--resume` ci-dessous.
5. Boucle principale (entrées TUI / headless `-p` / ACP : toutes doivent passer par l'étape 4)

**Différence avec la simplification de la Phase A :** L'outil `EnterWorktreeTool` de la Phase A **ne modifie pas** `Config.targetDir`, le modèle lit le chemin absolu depuis le résultat de l'outil et continue à l'utiliser. Le flag CLI de la Phase D agit au démarrage, sans contexte de modèle en cours d'exécution, donc **bascule directement `targetDir` et `process.cwd()`** — c'est une garantie d'isolation plus forte. Les deux chemins ont des comportements différents, à documenter dans la documentation utilisateur.

**Comportement de sortie :** Réutilise `WorktreeExitDialog` (déjà implémenté en Phase C). Ctrl+C/D deux fois → l'utilisateur choisit entre keep / remove / cancel. Pas de nouveau chemin de code.

**Priorité avec `--resume` :**

Le stockage de session étant basé sur `projectHash(process.cwd())` comme clé, et `--worktree` effectue un chdir vers le worktree avant le resume picker / `loadCliConfig`, "démarrer une session dans le worktree X et la reprendre depuis le worktree Y" est **architecturalement impossible** (leurs projectHash sont différents, les fichiers de session tombent dans des répertoires différents). Le tableau ci-dessous reflète le comportement réel après l'implémentation de D-1 + la correction de re-attachement de la Phase 6 :

| État `--resume`              | État `--worktree`               | Résultat                                                                              |
| ---------------------------- | ------------------------------- | ------------------------------------------------------------------------------------- |
| Aucun                        | Aucun                           | Session normale, pas de worktree                                                      |
| Aucun                        | Présent (nouveau slug)          | Création d'un nouveau worktree                                                        |
| Aucun                        | Présent (slug existant)         | **Re-attachement** au worktree existant (correction Phase 6)                          |
| Présent                      | Aucun                           | Reprise de l'ancien worktree (comportement Phase C, sidecar trouvé → injection d'un rappel) |
| Présent (sid du même worktree) | Présent (même slug, re-attachement) | Re-attachement + session trouvée : reprise normale                                   |
| Présent (sid du main checkout) | Présent (slug quelconque)      | **Échec de recherche de session** : `No saved session found with ID …`, exit 1. Limitation documentée |
| Présent (sid du worktree X) | Présent (slug Y, X != Y)        | Idem, session non trouvable entre différents projectHash                              |

Le remplacement de la clé projectHash par un ancrage sur la racine du dépôt pour le stockage intersession (permettant de transférer une session entre différents worktrees / main checkout) relève d'une future refonte de Config. Le code de la branche `overrodeResumedWorktree` dans `persistStartupWorktreeSidecar` est conservé pour s'activer automatiquement après cette refonte, mais ne sera pas déclenché dans le chemin de production actuel.

#### D-2 : Option de configuration `worktree.symlinkDirectories`

**Schéma :**

```jsonc
{
  "worktree": {
    "symlinkDirectories": ["node_modules", "dist", ".turbo"],
  },
}

git fetch origin pull/<N>/head
→ utilise FETCH_HEAD comme base du nouveau worktree