Merge feat/home-path-expansion into dev

- Add expand_container_path() helper that resolves ~/ and $HOME/ prefixes
- Add get_manifest_home_dir() to compute /home/{user.name} or /root from manifest
- Set ENV HOME=... and ENV USER=... in generated Dockerfile for runtime compatibility
- Pass home_dir through instance creation and startup pipeline
- Expand mount targets in apply_resolved_profile() for regular profile mounts
- Expand mapping targets in _resolve_git_mount_mappings() for git mounts
- Expand working_directory and volume targets in _modify_compose_file()
- Update _prepare_manifest_instance to return home_dir alongside image tag
- Fetch tool_type early in start_instance to determine home_dir before profile application

Quality gates: pytest 188 passed, frontend typecheck clean

Addresses: home-path-expansion

.atl/.skill-registry.cache.json

@@ -0,0 +1,3 @@
+{
+  "fingerprint": "c324de9e9faf30231900c691aca5f3a07c7db099"
+}

.atl/skill-registry.md

@@ -0,0 +1,34 @@
+# Skill Registry — headquarter
+
+<!-- Auto-generated by gentle-pi extensions/skill-registry.ts. Run /skill-registry:refresh to regenerate. -->
+
+Last updated: 2026-05-27
+
+## Sources scanned
+
+- .opencode/skills
+- /home/alex/.config/opencode/skills
+
+## Contract
+
+**Delegator use only.** This registry is an index, not a summary. Any agent that launches subagents reads it to select relevant skills, then passes exact `SKILL.md` paths for the subagent to read before work.
+
+`SKILL.md` remains the source of truth. Do not inject generated summaries or compact rules by default; pass paths so subagents load the full runtime contract and preserve author intent.
+
+## Skills
+
+| Skill | Trigger / description | Scope | Path |
+| --- | --- | --- | --- |
+| `auto-commit` | Use when you are making multiple edits or completing significant work in a git repository to automatically create commits | user | `/home/alex/.config/opencode/skills/auto-commit/SKILL.md` |
+| `openspec` | Use OpenSpec as the source of truth for planning, implementation, verification, and archive discipline. | user | `/home/alex/.config/opencode/skills/openspec/SKILL.md` |
+| `openspec-apply-change` | Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks. | project | `/home/alex/projects/headquarter/.opencode/skills/openspec-apply-change/SKILL.md` |
+| `openspec-archive-change` | Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete. | project | `/home/alex/projects/headquarter/.opencode/skills/openspec-archive-change/SKILL.md` |
+| `openspec-explore` | Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change. | project | `/home/alex/projects/headquarter/.opencode/skills/openspec-explore/SKILL.md` |
+| `openspec-propose` | Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation. | project | `/home/alex/projects/headquarter/.opencode/skills/openspec-propose/SKILL.md` |
+
+## Loading protocol
+
+1. Match task context and target files against the `Trigger / description` column.
+2. Pass only the matching `Path` values to the subagent under `## Skills to load before work`.
+3. Instruct the subagent to read those exact `SKILL.md` files before reading, writing, reviewing, testing, or creating artifacts.
+4. If no matching skill exists, proceed without project skill injection and report `skill_resolution: none`.

.gitignore

@@ -49,5 +49,8 @@ apps/web/dist/
 .DS_Store
 Thumbs.db
 /.stoneforge/.worktrees/
-# Local Pi runtime state
+# Pi / agent cache
+.pi/
 .atl/
+.sisyphus/
+.pi-lens/

.sisyphus/run-continuation/ses_1da2608b1ffergOzow3NQt1mGr.json

@@ -0,0 +1,10 @@
+{
+  "sessionID": "ses_1da2608b1ffergOzow3NQt1mGr",
+  "updatedAt": "2026-05-15T23:50:42.832Z",
+  "sources": {
+    "background-task": {
+      "state": "idle",
+      "updatedAt": "2026-05-15T23:50:42.832Z"
+    }
+  }
+}

apps/api/.pi-lens/cache/python-rules-v2.json

@@ -0,0 +1,568 @@
+{
+  "version": "v2",
+  "timestamp": 1779889907001,
+  "ruleHash": "fd9b2b15f2ac8993",
+  "queries": [
+    {
+      "id": "bare-except",
+      "name": "Bare Except Clause",
+      "severity": "warning",
+      "language": "python",
+      "message": "Bare 'except:' clause — catches SystemExit, KeyboardInterrupt",
+      "query": "  (except_clause\n    \"except\") @CLAUSE",
+      "metavars": [
+        "CLAUSE"
+      ],
+      "post_filter": "bare_except_only",
+      "defect_class": "silent-error",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/python/bare-except.yml"
+    },
+    {
+      "id": "eval-exec",
+      "name": "Eval/Exec Usage",
+      "severity": "warning",
+      "language": "python",
+      "message": "{{FUNC}}() detected — security risk, code injection vulnerability",
+      "query": "  (call\n    function: (identifier) @FUNC\n    (#match? @FUNC \"^(eval|exec)$\")\n    arguments: (argument_list) @ARGS)",
+      "metavars": [
+        "FUNC",
+        "ARGS"
+      ],
+      "defect_class": "injection",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/python/eval-exec.yml"
+    },
+    {
+      "id": "exit-signature-check",
+      "name": "__exit__ Missing Parameters",
+      "severity": "error",
+      "language": "python",
+      "message": "__exit__ should accept type, value, and traceback arguments",
+      "query": "  (function_definition\n    name: (identifier) @NAME (#eq? @NAME \"__exit__\")\n    parameters: (parameters\n      (_) @SELF\n      . (_) @PARAM1?\n      . (_) @PARAM2?\n      . (_) @PARAM3?))",
+      "metavars": [
+        "NAME",
+        "SELF",
+        "PARAM1",
+        "PARAM2",
+        "PARAM3"
+      ],
+      "post_filter": "exit_params_insufficient",
+      "defect_class": "correctness",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/python/exit-signature-check.yml"
+    },
+    {
+      "id": "in-operator-unsupported",
+      "name": "In and Not In Operators Should Be Used on Valid Objects",
+      "severity": "warning",
+      "language": "python",
+      "message": "'in' operator used on object that may not support containment",
+      "query": "  (comparison_operator\n    (identifier) @OBJ\n    \"in\"\n    (identifier) @TARGET)\n  (comparison_operator\n    (identifier) @OBJ\n    \"not\"\n    \"in\"\n    (identifier) @TARGET)",
+      "metavars": [
+        "OBJ",
+        "TARGET"
+      ],
+      "post_filter": "check_in_operator_types",
+      "defect_class": "correctness",
+      "inline_tier": "warning",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/python/in-operator-unsupported.yml"
+    },
+    {
+      "id": "is-vs-equals",
+      "name": "Is vs Equals for Literals",
+      "severity": "warning",
+      "language": "python",
+      "message": "Using 'is' with literal — use '==' for value comparison",
+      "query": "  (comparison_operator\n    (identifier)\n    (\"is\")\n    (string) @LITERAL)\n  (comparison_operator\n    (identifier)\n    (\"is not\")\n    (string) @LITERAL)\n  (comparison_operator\n    (identifier)\n    (\"is\")\n    (integer) @LITERAL)\n  (comparison_operator\n    (identifier)\n    (\"is not\")\n    (integer) @LITERAL)",
+      "metavars": [
+        "LITERAL"
+      ],
+      "defect_class": "correctness",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/python/is-vs-equals.yml"
+    },
+    {
+      "id": "iter-return-iterator",
+      "name": "__iter__ Should Return Iterator",
+      "severity": "warning",
+      "language": "python",
+      "message": "__iter__ should return an iterator (object with __next__ method)",
+      "query": "  (function_definition\n    name: (identifier) @NAME (#eq? @NAME \"__iter__\")\n    body: (block\n      (return_statement) @RETURN))",
+      "metavars": [
+        "NAME",
+        "RETURN"
+      ],
+      "defect_class": "correctness",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/python/iter-return-iterator.yml"
+    },
+    {
+      "id": "mutable-default-arg",
+      "name": "Mutable Default Argument",
+      "severity": "warning",
+      "language": "python",
+      "message": "Mutable default argument — list/dict/set as default value",
+      "query": "  (function_definition\n    (parameters\n      (default_parameter\n        (identifier) @PARAM\n        [(list) (dictionary) (set)] @MUTABLE)))",
+      "metavars": [
+        "PARAM",
+        "MUTABLE"
+      ],
+      "defect_class": "correctness",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/python/mutable-default-arg.yml"
+    },
+    {
+      "id": "no-super-torchscript",
+      "name": "super Should Not Be Used in TorchScript Methods",
+      "severity": "error",
+      "language": "python",
+      "message": "super() calls should not be used in TorchScript methods",
+      "query": "  (function_definition\n    (decorator\n      (call\n        function: (identifier) @DEC (#match? @DEC \"^(torch\\.jit\\.script|jit\\.script)$\")))\n    body: (block\n      (call\n        function: (identifier) @FUNC (#eq? @FUNC \"super\")) @CALL))",
+      "metavars": [
+        "DEC",
+        "FUNC",
+        "CALL"
+      ],
+      "defect_class": "correctness",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/python/no-super-torchscript.yml"
+    },
+    {
+      "id": "notimplemented-boolean-context",
+      "name": "NotImplemented in Boolean Context",
+      "severity": "error",
+      "language": "python",
+      "message": "NotImplemented should not be used in boolean contexts",
+      "query": "  (if_statement\n    condition: (identifier) @COND (#eq? @COND \"NotImplemented\"))\n  (while_statement\n    condition: (identifier) @COND (#eq? @COND \"NotImplemented\"))\n  (binary_operator\n    (identifier) @COND (#eq? @COND \"NotImplemented\")\n    (\"and\" | \"or\"))\n  (boolean_operator\n    (identifier) @COND (#eq? @COND \"NotImplemented\"))\n  (unary_operator\n    operator: (\"not\")\n    argument: (identifier) @COND (#eq? @COND \"NotImplemented\"))",
+      "metavars": [
+        "COND"
+      ],
+      "defect_class": "correctness",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/python/notimplemented-boolean-context.yml"
+    },
+    {
+      "id": "python-assert-production",
+      "name": "Assert in Production Code",
+      "severity": "warning",
+      "language": "python",
+      "message": "assert statement stripped by Python -O flag — use explicit checks with exceptions in production code",
+      "query": "  (assert_statement) @ASSERT",
+      "metavars": [
+        "ASSERT"
+      ],
+      "defect_class": "correctness",
+      "inline_tier": "warning",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/python/python-assert-production.yml"
+    },
+    {
+      "id": "python-command-injection",
+      "name": "Command Injection Sink",
+      "severity": "error",
+      "language": "python",
+      "message": "Potential command injection sink — avoid shell execution with dynamic input",
+      "query": "  (call\n    function: (attribute\n      object: (identifier) @MOD\n      attribute: (identifier) @FN)\n    arguments: (argument_list) @ARGS\n    (#eq? @MOD \"os\")\n    (#match? @FN \"^(system|popen)$\"))\n\n  (call\n    function: (attribute\n      object: (identifier) @MOD\n      attribute: (identifier) @FN)\n    arguments: (argument_list\n      (keyword_argument\n        name: (identifier) @KW\n        value: (true)))\n    (#eq? @MOD \"subprocess\")\n    (#match? @FN \"^(run|Popen|call|check_output|check_call)$\")\n    (#eq? @KW \"shell\"))",
+      "metavars": [
+        "MOD",
+        "FN",
+        "ARGS",
+        "KW"
+      ],
+      "post_filter": "py_command_injection_sink",
+      "defect_class": "injection",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/python/python-command-injection.yml"
+    },
+    {
+      "id": "python-cross-language-method",
+      "name": "Cross-Language Method Leakage",
+      "severity": "warning",
+      "language": "python",
+      "message": "'{METHOD}' is not a Python method — likely a {LANG} idiom leaking in",
+      "query": "  (call\n    function: (attribute\n      object: (_) @OBJ\n      attribute: (identifier) @METHOD)\n    (#match? @METHOD \"^(push|forEach|indexOf|charAt|substring|hasOwnProperty|unshift|flatMap|padStart|padEnd|trimStart|trimEnd|equals|isEmpty|println|printf|getClass|hashCode|toCharArray|getBytes|compareTo|equalsIgnoreCase|startsWith|endsWith|each|collect|select|reject|detect|inject|chomp|chop|gsub|upcase|downcase|present|blank|Add|Contains|ToLower|ToUpper|Trim|Substring|WriteLine|ReadLine|TryParse|forEach|includes|assign|freeze|splice|unshift|shift|flatMap)$\"))",
+      "metavars": [
+        "OBJ",
+        "METHOD"
+      ],
+      "post_filter": "match_captures",
+      "post_filter_params": {
+        "METHOD": "^(push|forEach|indexOf|charAt|substring|hasOwnProperty|unshift|flatMap|padStart|padEnd|trimStart|trimEnd|equals|isEmpty|println|printf|getClass|hashCode|toCharArray|getBytes|compareTo|equalsIgnoreCase|startsWith|endsWith|each|collect|select|reject|detect|inject|chomp|chop|gsub|upcase|downcase|present|blank|Add|Contains|ToLower|ToUpper|Trim|Substring|WriteLine|ReadLine|TryParse|forEach|includes|assign|freeze|splice|unshift|shift|flatMap)$"
+      },
+      "defect_class": "hallucination",
+      "inline_tier": "warning",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/python/python-cross-language-method.yml"
+    },
+    {
+      "id": "python-debugger",
+      "name": "Debugger Statement",
+      "severity": "warning",
+      "language": "python",
+      "message": "Debugger call '{{FUNC}}' — remove before committing",
+      "query": "  (call\n    function: (identifier) @FUNC\n    (#eq? @FUNC \"breakpoint\"))\n\n  (call\n    function: (attribute\n      object: (identifier) @MOD\n      attribute: (identifier) @FUNC)\n    (#eq? @MOD \"pdb\")\n    (#match? @FUNC \"^(set_trace|post_mortem|pm|run|runcall)$\"))",
+      "metavars": [
+        "FUNC",
+        "MOD"
+      ],
+      "defect_class": "safety",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/python/python-debugger.yml"
+    },
+    {
+      "id": "python-empty-except",
+      "name": "Empty Except Block",
+      "severity": "warning",
+      "language": "python",
+      "message": "Except block only contains 'pass' — handle or re-raise the exception",
+      "query": "  (try_statement\n    (except_clause\n      body: (block) @BODY))",
+      "metavars": [
+        "BODY"
+      ],
+      "post_filter": "python_empty_except",
+      "defect_class": "silent-error",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/python/python-empty-except.yml"
+    },
+    {
+      "id": "python-hallucinated-import",
+      "name": "Hallucinated Import",
+      "severity": "warning",
+      "language": "python",
+      "message": "Hallucinated import — '{NAME}' does not exist in '{MODULE}'",
+      "query": "  (import_from_statement\n    module_name: (dotted_name) @MODULE\n    name: (dotted_name) @NAME)",
+      "metavars": [
+        "MODULE",
+        "NAME"
+      ],
+      "post_filter": "match_captures",
+      "post_filter_params": {
+        "MODULE": "^(requests|flask|django|typing|collections|asyncio|json|unittest|pytest|urllib|sqlalchemy)$",
+        "NAME": "^(JSONResponse|HTMLResponse|RedirectResponse|StreamingResponse|Depends|Query|Path|Body|Header|Cookie|Form|File|UploadFile|FastAPI|APIRouter|HTTPException|BackgroundTasks|dataclass|fields|BaseModel|Field|validator|aiohttp|parse|stringify|fixture|TestCase|get|post|put|delete|Model|Session|Column|Integer|String)$"
+      },
+      "defect_class": "hallucination",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/python/python-hallucinated-import.yml"
+    },
+    {
+      "id": "python-hardcoded-secrets",
+      "name": "Hardcoded Secret",
+      "severity": "warning",
+      "language": "python",
+      "message": "Hardcoded {{VARNAME}} — use environment variables or a secrets manager",
+      "query": "  (assignment\n    left: (identifier) @VARNAME\n    right: (string) @VALUE)",
+      "metavars": [
+        "VARNAME",
+        "VALUE"
+      ],
+      "post_filter": "check_secret_pattern",
+      "defect_class": "secrets",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/python/python-hardcoded-secrets.yml"
+    },
+    {
+      "id": "python-insecure-deserialization",
+      "name": "Insecure Deserialization",
+      "severity": "error",
+      "language": "python",
+      "message": "Potential insecure deserialization sink — avoid unsafe loaders",
+      "query": "  (call\n    function: (attribute\n      object: (identifier) @MOD\n      attribute: (identifier) @FN)\n    arguments: (argument_list (_) @DATA)\n    (#match? @MOD \"^(pickle|yaml)$\")\n    (#match? @FN \"^(load|loads|unsafe_load)$\"))",
+      "metavars": [
+        "MOD",
+        "FN",
+        "DATA"
+      ],
+      "post_filter": "py_insecure_deserialization_sink",
+      "defect_class": "injection",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/python/python-insecure-deserialization.yml"
+    },
+    {
+      "id": "python-insecure-random",
+      "name": "Insecure Randomness",
+      "severity": "warning",
+      "language": "python",
+      "message": "Insecure randomness source detected — use secrets or os.urandom for security-sensitive values",
+      "query": "  (call\n    function: (attribute\n      object: (identifier) @MOD\n      attribute: (identifier) @FN)\n    arguments: (argument_list) @ARGS\n    (#eq? @MOD \"random\")\n    (#match? @FN \"^(random|randint|randrange|choice|choices)$\"))",
+      "metavars": [
+        "MOD",
+        "FN",
+        "ARGS"
+      ],
+      "defect_class": "injection",
+      "inline_tier": "warning",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/python/python-insecure-random.yml"
+    },
+    {
+      "id": "python-mutable-class-attr",
+      "name": "Mutable Class Attribute",
+      "severity": "warning",
+      "language": "python",
+      "message": "Class attribute '{{VARNAME}}' is mutable — shared across all instances",
+      "query": "  (class_definition\n    body: (block\n      (expression_statement\n        (assignment\n          left: (identifier) @VARNAME\n          right: [\n            (list) @VALUE\n            (dictionary) @VALUE\n            (set) @VALUE\n          ]))))",
+      "metavars": [
+        "VARNAME",
+        "VALUE"
+      ],
+      "post_filter": "not_in_function",
+      "defect_class": "correctness",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/python/python-mutable-class-attr.yml"
+    },
+    {
+      "id": "python-path-traversal",
+      "name": "Path Traversal Risk",
+      "severity": "warning",
+      "language": "python",
+      "message": "Potential path traversal sink — sanitize and constrain file paths",
+      "query": "  [\n    (call\n      function: (identifier) @FN\n      arguments: (argument_list\n        [(identifier) (binary_operator) (call)] @PATH))\n    (call\n      function: (attribute\n        object: (identifier) @MOD\n        attribute: (identifier) @FN)\n      arguments: (argument_list\n        [(identifier) (binary_operator) (call)] @PATH))\n  ]\n  (#match? @FN \"^(open|read_text|read_bytes|write_text|write_bytes|remove|unlink|rmdir)$\")",
+      "metavars": [
+        "MOD",
+        "FN",
+        "PATH"
+      ],
+      "post_filter": "py_path_traversal_sink",
+      "defect_class": "injection",
+      "inline_tier": "warning",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/python/python-path-traversal.yml"
+    },
+    {
+      "id": "python-print-statement",
+      "name": "Print Statement in Production",
+      "severity": "warning",
+      "language": "python",
+      "message": "print() — remove debug output before committing",
+      "query": "  (call\n    function: (identifier) @FUNC\n    (#eq? @FUNC \"print\")\n    arguments: (argument_list) @ARGS)",
+      "metavars": [
+        "FUNC",
+        "ARGS"
+      ],
+      "post_filter": "not_in_test_block",
+      "defect_class": "safety",
+      "inline_tier": "warning",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/python/python-print-statement.yml"
+    },
+    {
+      "id": "python-raise-string",
+      "name": "Raise String Instead of Exception",
+      "severity": "warning",
+      "language": "python",
+      "message": "raise with string literal — Python 3 requires exception instances",
+      "query": "  (raise_statement\n    (string) @VALUE)",
+      "metavars": [
+        "VALUE"
+      ],
+      "defect_class": "correctness",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/python/python-raise-string.yml"
+    },
+    {
+      "id": "python-sleep-in-test",
+      "name": "time.sleep in Test",
+      "severity": "warning",
+      "language": "python",
+      "message": "time.sleep() in test — use synchronisation primitives or polling helpers instead of fixed sleeps",
+      "query": "  (call\n    function: (attribute\n      object: (identifier) @MOD\n      attribute: (identifier) @FN)\n    (#eq? @MOD \"time\")\n    (#eq? @FN \"sleep\")) @CALL",
+      "metavars": [
+        "MOD",
+        "FN",
+        "CALL"
+      ],
+      "defect_class": "async-misuse",
+      "inline_tier": "warning",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/python/python-sleep-in-test.yml"
+    },
+    {
+      "id": "python-sql-injection",
+      "name": "SQL Injection Risk",
+      "severity": "error",
+      "language": "python",
+      "message": "Potential SQL injection sink — use parameterized queries",
+      "query": "  (call\n    function: (attribute\n      object: (_) @OBJ\n      attribute: (identifier) @FN)\n    arguments: (argument_list\n      [(binary_operator) (identifier) (call)] @SQL\n      (_)*))",
+      "metavars": [
+        "OBJ",
+        "FN",
+        "SQL"
+      ],
+      "post_filter": "py_sql_injection_sink",
+      "defect_class": "injection",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/python/python-sql-injection.yml"
+    },
+    {
+      "id": "python-ssrf",
+      "name": "SSRF Risk",
+      "severity": "warning",
+      "language": "python",
+      "message": "Potential SSRF sink — validate/allowlist outbound URLs",
+      "query": "  (call\n    function: (attribute\n      object: (identifier) @MOD\n      attribute: (identifier) @FN)\n    arguments: (argument_list\n      [(identifier) (subscript) (call)] @URL)\n    (#eq? @MOD \"requests\")\n    (#match? @FN \"^(get|post|put|patch|delete|request|head|options)$\"))",
+      "metavars": [
+        "MOD",
+        "FN",
+        "URL"
+      ],
+      "post_filter": "py_ssrf_sink",
+      "defect_class": "injection",
+      "inline_tier": "warning",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/python/python-ssrf.yml"
+    },
+    {
+      "id": "python-subprocess-shell",
+      "name": "subprocess with shell=True",
+      "severity": "warning",
+      "language": "python",
+      "message": "subprocess called with shell=True — command injection risk if any argument is user-controlled",
+      "query": "  (call\n    function: (attribute\n      object: (identifier) @MOD\n      attribute: (identifier) @FN)\n    arguments: (argument_list\n      (keyword_argument\n        name: (identifier) @KW\n        value: (true) @VAL))\n    (#eq? @MOD \"subprocess\")\n    (#match? @FN \"^(run|Popen|call|check_output|check_call)$\")\n    (#eq? @KW \"shell\"))",
+      "metavars": [
+        "MOD",
+        "FN",
+        "KW"
+      ],
+      "defect_class": "injection",
+      "inline_tier": "warning",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/python/python-subprocess-shell.yml"
+    },
+    {
+      "id": "python-thread-global-write",
+      "name": "Threaded Shared State Risk",
+      "severity": "warning",
+      "language": "python",
+      "message": "Thread creation detected — ensure shared state mutations are synchronized",
+      "query": "  (call\n    function: (attribute\n      object: (identifier) @MOD\n      attribute: (identifier) @FN)\n    arguments: (argument_list) @ARGS)\n  (#eq? @MOD \"threading\")\n  (#eq? @FN \"Thread\")",
+      "metavars": [
+        "MOD",
+        "FN",
+        "ARGS"
+      ],
+      "defect_class": "async-misuse",
+      "inline_tier": "warning",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/python/python-thread-global-write.yml"
+    },
+    {
+      "id": "python-unsafe-regex",
+      "name": "Unsafe Dynamic Regex",
+      "severity": "warning",
+      "language": "python",
+      "message": "re.{{FUNC}}() with variable pattern — ReDoS risk if pattern is user-controlled",
+      "query": "  (call\n    function: (attribute\n      object: (identifier) @MOD\n      attribute: (identifier) @FUNC)\n    arguments: (argument_list\n      (identifier) @PATTERN)\n    (#eq? @MOD \"re\")\n    (#match? @FUNC \"^(compile|match|search|fullmatch|findall|finditer|sub|subn|split)$\"))",
+      "metavars": [
+        "MOD",
+        "FUNC",
+        "PATTERN"
+      ],
+      "defect_class": "injection",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/python/python-unsafe-regex.yml"
+    },
+    {
+      "id": "python-weak-hash",
+      "name": "Weak Hash Primitive",
+      "severity": "error",
+      "language": "python",
+      "message": "Weak hash primitive detected (MD5/SHA1) — use SHA-256+ for security-sensitive contexts",
+      "query": "  (call\n    function: (attribute\n      object: (identifier) @MOD\n      attribute: (identifier) @FN)\n    arguments: (argument_list) @ARGS\n    (#eq? @MOD \"hashlib\")\n    (#match? @FN \"^(md5|sha1)$\"))",
+      "metavars": [
+        "MOD",
+        "FN",
+        "ARGS"
+      ],
+      "defect_class": "injection",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/python/python-weak-hash.yml"
+    },
+    {
+      "id": "return-in-generator",
+      "name": "Return with Value in Generator",
+      "severity": "error",
+      "language": "python",
+      "message": "'return' with a value should not be used in a generator function",
+      "query": "  (function_definition\n    body: (block\n      (return_statement\n        (_) @RETURN_VAL) @RETURN)) @FUNCTION",
+      "metavars": [
+        "FUNCTION",
+        "RETURN",
+        "RETURN_VAL"
+      ],
+      "post_filter": "is_generator_with_valued_return",
+      "defect_class": "correctness",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/python/return-in-generator.yml"
+    },
+    {
+      "id": "return-in-init",
+      "name": "Return Value in __init__",
+      "severity": "error",
+      "language": "python",
+      "message": "__init__ should not return a value — it must always return None",
+      "query": "  (function_definition\n    name: (identifier) @NAME (#eq? @NAME \"__init__\")\n    body: (block\n      (return_statement\n        (_) @RETURN_VAL) @RETURN))",
+      "metavars": [
+        "NAME",
+        "RETURN",
+        "RETURN_VAL"
+      ],
+      "post_filter": "has_return_value",
+      "defect_class": "correctness",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/python/return-in-init.yml"
+    },
+    {
+      "id": "send-file-mimetype",
+      "name": "send_file Should Specify Mimetype or Download Name",
+      "severity": "error",
+      "language": "python",
+      "message": "send_file should specify 'mimetype' or 'download_name' when used with file-like objects",
+      "query": "  (call\n    function: (identifier) @FUNC (#eq? @FUNC \"send_file\")\n    arguments: (argument_list\n      (_) @FIRST_ARG\n      (keyword_argument)? @KW))",
+      "metavars": [
+        "FUNC",
+        "FIRST_ARG",
+        "KW"
+      ],
+      "post_filter": "missing_mimetype_and_download_name",
+      "defect_class": "correctness",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/python/send-file-mimetype.yml"
+    },
+    {
+      "id": "unreachable-except",
+      "name": "Unreachable Except Clause",
+      "severity": "warning",
+      "language": "python",
+      "message": "Unreachable except clause — earlier except catches all",
+      "query": "  (try_statement\n    (except_clause\n      \"except\") @GENERAL\n    (except_clause\n      \"except\"\n      (identifier) @SPECIFIC))",
+      "metavars": [
+        "GENERAL",
+        "SPECIFIC"
+      ],
+      "defect_class": "correctness",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/python/unreachable-except.yml"
+    },
+    {
+      "id": "wildcard-import",
+      "name": "Wildcard Import",
+      "severity": "warning",
+      "language": "python",
+      "message": "Wildcard import — pollutes namespace, hard to track origin",
+      "query": "  (import_from_statement\n    module_name: (dotted_name) @MODULE\n    (wildcard_import) @WILDCARD)",
+      "metavars": [
+        "MODULE",
+        "WILDCARD"
+      ],
+      "defect_class": "safety",
+      "inline_tier": "warning",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/python/wildcard-import.yml"
+    },
+    {
+      "id": "yield-return-outside-function",
+      "name": "Yield/Return Outside Function",
+      "severity": "error",
+      "language": "python",
+      "message": "{{STATEMENT}} used outside function — syntax error",
+      "query": "  (module\n    (expression_statement\n      (yield) @STATEMENT))\n  (module\n    (expression_statement\n      (yield_expression) @STATEMENT))\n  (module\n    (return_statement) @STATEMENT)",
+      "metavars": [
+        "STATEMENT"
+      ],
+      "defect_class": "correctness",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/python/yield-return-outside-function.yml"
+    }
+  ]
+}

apps/api/alembic/versions/2026_05_28_add_terminal_sessions_table.py

@@ -0,0 +1,61 @@
+"""add terminal_sessions table
+
+Revision ID: 2026_05_28_add_terminal_sessions
+Revises: 20260527_160017_add_pi_agent
+Create Date: 2026-05-28
+
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision: str = "2026_05_28_add_terminal_sessions"
+down_revision: str | None = "2026_05_28_add_tool_definition_manifests"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "terminal_sessions",
+        sa.Column("id", sa.UUID(), nullable=False),
+        sa.Column("instance_id", sa.UUID(), nullable=False),
+        sa.Column("name", sa.String(length=255), nullable=True),
+        sa.Column("status", sa.String(length=50), nullable=False),
+        sa.Column("last_activity_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("closed_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            onupdate=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.ForeignKeyConstraint(
+            ["instance_id"], ["tool_instances.id"], ondelete="CASCADE"
+        ),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(
+        op.f("ix_terminal_sessions_instance_id"),
+        "terminal_sessions",
+        ["instance_id"],
+        unique=False,
+    )
+
+
+def downgrade() -> None:
+    op.drop_index(
+        op.f("ix_terminal_sessions_instance_id"),
+        table_name="terminal_sessions",
+    )
+    op.drop_table("terminal_sessions")

apps/api/alembic/versions/2026_05_28_drop_tool_configs_and_config_folders.py

@@ -0,0 +1,89 @@
+"""drop tool_configs and config_folders tables
+
+Revision ID: 2026_05_28_drop_tool_configs_and_config_folders
+Revises: 2026_05_28_add_tool_definition_manifests
+Create Date: 2026-05-28
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision: str = "2026_05_28_drop_tool_configs_and_config_folders"
+down_revision: Union[str, None] = "2026_05_28_add_terminal_sessions"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+
+    # Drop tool_configs table if it exists
+    result = conn.execute(
+        sa.text("""
+            SELECT table_name FROM information_schema.tables
+            WHERE table_name = 'tool_configs'
+        """)
+    )
+    if result.fetchone():
+        op.drop_table("tool_configs")
+
+    # Drop config_folders table if it exists
+    result = conn.execute(
+        sa.text("""
+            SELECT table_name FROM information_schema.tables
+            WHERE table_name = 'config_folders'
+        """)
+    )
+    if result.fetchone():
+        op.drop_table("config_folders")
+
+
+def downgrade() -> None:
+    # Recreate config_folders table
+    op.create_table(
+        "config_folders",
+        sa.Column("id", sa.UUID(), nullable=False),
+        sa.Column("user_id", sa.UUID(), nullable=False),
+        sa.Column("name", sa.String(255), nullable=False),
+        sa.Column("description", sa.Text(), nullable=True),
+        sa.Column("mount_path", sa.String(1024), nullable=False),
+        sa.Column("files", sa.JSON(), default=dict, nullable=False),
+        sa.Column("project_overrides", sa.JSON(), default=dict, nullable=True),
+        sa.Column("is_active", sa.Boolean(), default=True, nullable=False),
+        sa.Column(
+            "created_at", sa.TIMESTAMP(timezone=True), server_default=sa.func.now()
+        ),
+        sa.Column(
+            "updated_at", sa.TIMESTAMP(timezone=True), server_default=sa.func.now()
+        ),
+        sa.PrimaryKeyConstraint("id"),
+    )
+
+    # Recreate tool_configs table
+    op.create_table(
+        "tool_configs",
+        sa.Column("id", sa.UUID(), nullable=False),
+        sa.Column("user_id", sa.UUID(), nullable=False),
+        sa.Column("tool_type_id", sa.UUID(), nullable=False),
+        sa.Column("project_id", sa.UUID(), nullable=True),
+        sa.Column("key", sa.String(255), nullable=False),
+        sa.Column("value", sa.Text(), nullable=False),
+        sa.Column("config_type", sa.String(20), default="env", nullable=False),
+        sa.Column("file_path", sa.String(1024), nullable=True),
+        sa.Column("port_override", sa.Integer(), nullable=True),
+        sa.Column("start_command", sa.Text(), nullable=True),
+        sa.Column("working_directory", sa.Text(), nullable=True),
+        sa.Column("environment_variables", sa.JSON(), default=dict, nullable=True),
+        sa.Column("volumes", sa.JSON(), default=list, nullable=True),
+        sa.Column(
+            "created_at", sa.TIMESTAMP(timezone=True), server_default=sa.func.now()
+        ),
+        sa.Column(
+            "updated_at", sa.TIMESTAMP(timezone=True), server_default=sa.func.now()
+        ),
+        sa.PrimaryKeyConstraint("id"),
+    )

apps/api/src/api/config_folders.py

@@ -1,337 +0,0 @@
-"""Config folder API endpoints."""
-
-import logging
-import uuid
-
-from fastapi import APIRouter, Depends, HTTPException, status
-from pydantic import BaseModel, Field, field_validator
-from sqlalchemy import select
-from sqlalchemy.ext.asyncio import AsyncSession
-
-from src.api.shared_validators import validate_files as _validate_files, validate_mount_path as _validate_mount_path
-from src.auth.dependencies import get_current_user_id, get_db_session
-from src.models.config_folder import ConfigFolder
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter(prefix="/config-folders", tags=["config-folders"])
-
-
-class ConfigFolderCreate(BaseModel):
-    name: str = Field(description="Folder name (unique per user)")
-    description: str | None = Field(default=None, description="Optional description")
-    mount_path: str = Field(description="Default mount path in container")
-    files: dict = Field(default_factory=dict, description="Files as {path: content}")
-
-    @field_validator("mount_path")
-    @classmethod
-    def validate_mount_path(cls, v: str) -> str:
-        return _validate_mount_path(v)
-
-    @field_validator("files")
-    @classmethod
-    def validate_files(cls, v: dict) -> dict:
-        return _validate_files(v)
-
-
-class ConfigFolderUpdate(BaseModel):
-    name: str | None = Field(default=None, description="Folder name")
-    description: str | None = Field(default=None, description="Optional description")
-    mount_path: str | None = Field(default=None, description="Default mount path")
-    files: dict | None = Field(default=None, description="Files as {path: content}")
-    is_active: bool | None = Field(default=None, description="Active/inactive toggle")
-
-    @field_validator("mount_path")
-    @classmethod
-    def validate_mount_path(cls, v: str | None) -> str | None:
-        return _validate_mount_path(v)
-
-    @field_validator("files")
-    @classmethod
-    def validate_files(cls, v: dict | None) -> dict | None:
-        return _validate_files(v)
-
-
-class ProjectOverrideCreate(BaseModel):
-    mount_path: str | None = Field(default=None, description="Override mount path")
-    files: dict = Field(default_factory=dict, description="Override files")
-
-    @field_validator("mount_path")
-    @classmethod
-    def validate_mount_path(cls, v: str | None) -> str | None:
-        return _validate_mount_path(v)
-
-
-class ConfigFolderResponse(BaseModel):
-    id: str
-    user_id: str
-    name: str
-    description: str | None
-    mount_path: str
-    files: dict
-    project_overrides: dict | None
-    is_active: bool
-    created_at: str
-    updated_at: str
-
-
-@router.get("", summary="List config folders", description="Get all config folders for the current user.")
-async def list_config_folders(
-    user_id: uuid.UUID = Depends(get_current_user_id),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    """List config folders for the current user."""
-    query = select(ConfigFolder).where(ConfigFolder.user_id == user_id)
-    result = await session.execute(query)
-    folders = result.scalars().all()
-    
-    return {
-        "folders": [
-            {
-                "id": str(f.id),
-                "user_id": str(f.user_id),
-                "name": f.name,
-                "description": f.description,
-                "mount_path": f.mount_path,
-                "files": f.files,
-                "project_overrides": f.project_overrides,
-                "is_active": f.is_active,
-                "created_at": f.created_at.isoformat() if f.created_at else None,
-                "updated_at": f.updated_at.isoformat() if f.updated_at else None,
-            }
-            for f in folders
-        ]
-    }
-
-
-@router.post("", summary="Create config folder", description="Create a new config folder.", status_code=status.HTTP_201_CREATED)
-async def create_config_folder(
-    data: ConfigFolderCreate,
-    user_id: uuid.UUID = Depends(get_current_user_id),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    """Create a config folder."""
-    # Check for duplicate name
-    existing = await session.scalar(
-        select(ConfigFolder).where(
-            ConfigFolder.user_id == user_id,
-            ConfigFolder.name == data.name,
-        )
-    )
-    if existing:
-        raise HTTPException(
-            status_code=status.HTTP_409_CONFLICT,
-            detail=f"config folder with name '{data.name}' already exists"
-        )
-    
-    folder = ConfigFolder(
-        user_id=user_id,
-        name=data.name,
-        description=data.description,
-        mount_path=data.mount_path,
-        files=data.files,
-    )
-    session.add(folder)
-    await session.commit()
-    await session.refresh(folder)
-    
-    return {
-        "id": str(folder.id),
-        "user_id": str(folder.user_id),
-        "name": folder.name,
-        "description": folder.description,
-        "mount_path": folder.mount_path,
-        "files": folder.files,
-        "project_overrides": folder.project_overrides,
-        "is_active": folder.is_active,
-        "created_at": folder.created_at.isoformat() if folder.created_at else None,
-        "updated_at": folder.updated_at.isoformat() if folder.updated_at else None,
-    }
-
-
-@router.put("/{folder_id}", summary="Update config folder", description="Update an existing config folder.")
-async def update_config_folder(
-    folder_id: uuid.UUID,
-    data: ConfigFolderUpdate,
-    user_id: uuid.UUID = Depends(get_current_user_id),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    """Update a config folder."""
-    folder = await session.get(ConfigFolder, folder_id)
-    if folder is None or folder.user_id != user_id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="config folder not found")
-    
-    if data.name is not None:
-        folder.name = data.name
-    if data.description is not None:
-        folder.description = data.description
-    if data.mount_path is not None:
-        folder.mount_path = data.mount_path
-    if data.files is not None:
-        folder.files = data.files
-    if data.is_active is not None:
-        folder.is_active = data.is_active
-    
-    await session.commit()
-    await session.refresh(folder)
-    
-    return {
-        "id": str(folder.id),
-        "user_id": str(folder.user_id),
-        "name": folder.name,
-        "description": folder.description,
-        "mount_path": folder.mount_path,
-        "files": folder.files,
-        "project_overrides": folder.project_overrides,
-        "is_active": folder.is_active,
-        "created_at": folder.created_at.isoformat() if folder.created_at else None,
-        "updated_at": folder.updated_at.isoformat() if folder.updated_at else None,
-    }
-
-
-@router.delete("/{folder_id}", summary="Delete config folder", description="Delete a config folder.", status_code=status.HTTP_204_NO_CONTENT)
-async def delete_config_folder(
-    folder_id: uuid.UUID,
-    user_id: uuid.UUID = Depends(get_current_user_id),
-    session: AsyncSession = Depends(get_db_session),
-) -> None:
-    """Delete a config folder."""
-    folder = await session.get(ConfigFolder, folder_id)
-    if folder is None or folder.user_id != user_id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="config folder not found")
-    
-    await session.delete(folder)
-    await session.commit()
-
-
-class ProjectOverrideWithId(ProjectOverrideCreate):
-    project_id: uuid.UUID = Field(description="Project ID for the override")
-
-
-@router.get("/{folder_id}", summary="Get config folder by ID", description="Get a single config folder by its ID.")
-async def get_config_folder(
-    folder_id: uuid.UUID,
-    user_id: uuid.UUID = Depends(get_current_user_id),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    """Get a config folder by ID."""
-    folder = await session.get(ConfigFolder, folder_id)
-    if folder is None or folder.user_id != user_id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="config folder not found")
-    
-    return {
-        "id": str(folder.id),
-        "user_id": str(folder.user_id),
-        "name": folder.name,
-        "description": folder.description,
-        "mount_path": folder.mount_path,
-        "files": folder.files,
-        "project_overrides": folder.project_overrides,
-        "is_active": folder.is_active,
-        "created_at": folder.created_at.isoformat() if folder.created_at else None,
-        "updated_at": folder.updated_at.isoformat() if folder.updated_at else None,
-    }
-
-
-@router.post("/{folder_id}/overrides", summary="Add project override", description="Add a project override to a config folder.")
-async def add_project_override(
-    folder_id: uuid.UUID,
-    data: ProjectOverrideWithId,
-    user_id: uuid.UUID = Depends(get_current_user_id),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    """Add a project override to a config folder."""
-    folder = await session.get(ConfigFolder, folder_id)
-    if folder is None or folder.user_id != user_id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="config folder not found")
-    
-    # Initialize project_overrides if None
-    if folder.project_overrides is None:
-        folder.project_overrides = {}
-    
-    # Add/update override
-    override_data = {}
-    if data.mount_path is not None:
-        override_data["mount_path"] = data.mount_path
-    if data.files is not None:
-        override_data["files"] = data.files
-    
-    # Use a copy to trigger SQLAlchemy change detection on JSONB
-    current_overrides = dict(folder.project_overrides or {})
-    current_overrides[str(data.project_id)] = override_data
-    folder.project_overrides = current_overrides
-    
-    await session.commit()
-    await session.refresh(folder)
-    
-    return {
-        "id": str(folder.id),
-        "project_overrides": folder.project_overrides,
-    }
-
-
-@router.put("/{folder_id}/overrides/{project_id}", summary="Update project override", description="Update a project override.")
-async def update_project_override(
-    folder_id: uuid.UUID,
-    project_id: uuid.UUID,
-    data: ProjectOverrideCreate,
-    user_id: uuid.UUID = Depends(get_current_user_id),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    """Update a project override."""
-    folder = await session.get(ConfigFolder, folder_id)
-    if folder is None or folder.user_id != user_id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="config folder not found")
-    
-    # Initialize project_overrides if None
-    if folder.project_overrides is None:
-        folder.project_overrides = {}
-    
-    # Update override
-    current_overrides = dict(folder.project_overrides or {})
-    override_data = current_overrides.get(str(project_id), {})
-    if data.mount_path is not None:
-        override_data["mount_path"] = data.mount_path
-    if data.files is not None:
-        override_data["files"] = data.files
-    
-    current_overrides[str(project_id)] = override_data
-    folder.project_overrides = current_overrides
-    
-    # Mark the field as modified to ensure SQLAlchemy detects the change
-    from sqlalchemy.orm.attributes import flag_modified
-    flag_modified(folder, "project_overrides")
-    
-    await session.commit()
-    await session.refresh(folder)
-    
-    return {
-        "id": str(folder.id),
-        "project_overrides": folder.project_overrides,
-    }
-
-
-@router.delete("/{folder_id}/overrides/{project_id}", summary="Remove project override", description="Remove a project override.")
-async def remove_project_override(
-    folder_id: uuid.UUID,
-    project_id: uuid.UUID,
-    user_id: uuid.UUID = Depends(get_current_user_id),
-    session: AsyncSession = Depends(get_db_session),
-) -> None:
-    """Remove a project override."""
-    folder = await session.get(ConfigFolder, folder_id)
-    if folder is None or folder.user_id != user_id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="config folder not found")
-    
-    # Remove override if exists
-    current_overrides = dict(folder.project_overrides or {})
-    if str(project_id) in current_overrides:
-        del current_overrides[str(project_id)]
-        folder.project_overrides = current_overrides
-        await session.commit()
-        await session.refresh(folder)
-    
-    return {
-        "id": str(folder.id),
-        "project_overrides": folder.project_overrides or {},
-    }

apps/api/src/api/config_profiles.py

@@ -2,9 +2,10 @@
 
 import logging
 import uuid
+from typing import Any
 
 from fastapi import APIRouter, Depends, HTTPException, Query, status
-from pydantic import BaseModel, Field, field_validator
+from pydantic import BaseModel, Field, field_validator, model_validator
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import selectinload
@@ -56,18 +57,11 @@ def _calculate_profile_size(data: dict) -> int:
     return total
 
 
-class GitMountItem(BaseModel):
-    remote_url: str = Field(description="Git remote URL (HTTPS or SSH)")
-    source_path: str = Field(default=".", description="Path within repository (supports glob patterns)")
+class GitMountMapping(BaseModel):
+    source_path: str = Field(
+        description="Path within repository (supports glob patterns)"
+    )
     target_path: str = Field(description="Absolute path inside container")
-    branch: str | None = Field(default=None, description="Optional branch or tag name")
-
-    @field_validator("remote_url")
-    @classmethod
-    def validate_remote_url(cls, v: str) -> str:
-        if not v.startswith(("http://", "https://", "git@", "ssh://")):
-            raise ValueError("remote_url must be a valid git URL (https://, git@, or ssh://)")
-        return v
 
     @field_validator("source_path")
     @classmethod
@@ -86,10 +80,66 @@ class GitMountItem(BaseModel):
         return v
 
 
+class GitMountItem(BaseModel):
+    remote_url: str = Field(description="Git remote URL (HTTPS or SSH)")
+    source_path: str | None = Field(
+        default=None, description="Path within repository (legacy single mapping)"
+    )
+    target_path: str | None = Field(
+        default=None,
+        description="Absolute path inside container (legacy single mapping)",
+    )
+    branch: str | None = Field(default=None, description="Optional branch or tag name")
+    mappings: list[GitMountMapping] | None = Field(
+        default=None, description="Multiple source/target mappings from the same repo"
+    )
+
+    @field_validator("remote_url")
+    @classmethod
+    def validate_remote_url(cls, v: str) -> str:
+        if not v.startswith(("http://", "https://", "git@", "ssh://")):
+            raise ValueError(
+                "remote_url must be a valid git URL (https://, git@, or ssh://)"
+            )
+        return v
+
+    @field_validator("source_path")
+    @classmethod
+    def validate_source_path(cls, v: str | None) -> str | None:
+        if v is None:
+            return v
+        if v.startswith("/"):
+            raise ValueError("source_path must be relative (no leading /)")
+        if ".." in v:
+            raise ValueError("source_path cannot contain path traversal (..)")
+        return v
+
+    @field_validator("target_path")
+    @classmethod
+    def validate_target_path(cls, v: str | None) -> str | None:
+        if v is None:
+            return v
+        if ".." in v:
+            raise ValueError("target_path cannot contain path traversal (..)")
+        return v
+
+    @model_validator(mode="after")
+    def check_mappings_or_legacy(self):
+        has_legacy = self.source_path is not None and self.target_path is not None
+        has_mappings = self.mappings is not None and len(self.mappings) > 0
+        if not has_legacy and not has_mappings:
+            raise ValueError(
+                "Git mount must have either 'mappings' (non-empty array) or both 'source_path' and 'target_path'"
+            )
+        return self
+
+
 class MountItem(BaseModel):
     target: str = Field(description="Absolute mount target path")
     mode: str = Field(default="rw", description="Mount mode: ro or rw")
-    files: dict = Field(default_factory=dict, description="Files as {relative_path: content}")
+    files: dict = Field(
+        default_factory=dict, description="Files as {relative_path: content}"
+    )
 
     @field_validator("target")
     @classmethod
@@ -126,10 +176,18 @@ class ConfigProfileCreate(BaseModel):
     tool_type_id: str | None = Field(default=None, description="Optional tool type ID")
     env_vars: dict = Field(default_factory=dict, description="Environment variables")
     runtime_hints: dict = Field(default_factory=dict, description="Runtime hints")
-    mounts: list[MountItem] = Field(default_factory=list, description="Mount definitions")
-    files: dict = Field(default_factory=dict, description="Files as {relative_path: content}")
-    git_mounts: list[GitMountItem] = Field(default_factory=list, description="Git repository mounts")
-    is_default: bool = Field(default=False, description="Whether this is the default profile for its scope")
+    mounts: list[MountItem] = Field(
+        default_factory=list, description="Mount definitions"
+    )
+    files: dict = Field(
+        default_factory=dict, description="Files as {relative_path: content}"
+    )
+    git_mounts: list[GitMountItem] = Field(
+        default_factory=list, description="Git repository mounts"
+    )
+    is_default: bool = Field(
+        default=False, description="Whether this is the default profile for its scope"
+    )
 
     @field_validator("project_id", "tool_type_id")
     @classmethod
@@ -179,10 +237,18 @@ class ConfigProfileUpdate(BaseModel):
     tool_type_id: str | None = Field(default=None, description="Optional tool type ID")
     env_vars: dict | None = Field(default=None, description="Environment variables")
     runtime_hints: dict | None = Field(default=None, description="Runtime hints")
-    mounts: list[MountItem] | None = Field(default=None, description="Mount definitions")
-    files: dict | None = Field(default=None, description="Files as {relative_path: content}")
-    git_mounts: list[GitMountItem] | None = Field(default=None, description="Git repository mounts")
-    is_default: bool | None = Field(default=None, description="Whether this is the default profile")
+    mounts: list[MountItem] | None = Field(
+        default=None, description="Mount definitions"
+    )
+    files: dict | None = Field(
+        default=None, description="Files as {relative_path: content}"
+    )
+    git_mounts: list[GitMountItem] | None = Field(
+        default=None, description="Git repository mounts"
+    )
+    is_default: bool | None = Field(
+        default=None, description="Whether this is the default profile"
+    )
 
     @field_validator("project_id", "tool_type_id")
     @classmethod
@@ -232,7 +298,9 @@ class ConfigProfileResponse(BaseModel):
     updated_at: str
 
 
-async def _get_profile_with_includes(session: AsyncSession, profile_id: uuid.UUID) -> ConfigProfile | None:
+async def _get_profile_with_includes(
+    session: AsyncSession, profile_id: uuid.UUID
+) -> ConfigProfile | None:
     """Fetch a profile with includes eagerly loaded."""
     result = await session.execute(
         select(ConfigProfile)
@@ -252,22 +320,26 @@ async def _check_access(
     if project_id is not None:
         project = await session.get(Project, project_id)
         if project is None:
-            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Project not found")
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND, detail="Project not found"
+            )
         # Add ownership check if needed; for now just verify existence
     if tool_type_id is not None:
         tool_type = await session.get(ToolType, tool_type_id)
         if tool_type is None:
-            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Tool type not found")
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND, detail="Tool type not found"
+            )
 
 
 async def _validate_git_mounts(
     session: AsyncSession,
     user_id: uuid.UUID,
-    git_mounts: list[dict],
+    git_mounts: list[Any],
     project_id: uuid.UUID | None = None,
 ) -> None:
     """Validate git mount URLs.
-    
+
     Simply checks that remote_url looks like a valid git URL.
     Actual clone validation happens at instance startup time.
     """
@@ -278,7 +350,7 @@ async def _validate_git_mounts(
                 status_code=status.HTTP_400_BAD_REQUEST,
                 detail="Git mount missing remote_url",
             )
-        
+
         if not remote_url.startswith(("http://", "https://", "git@", "ssh://")):
             raise HTTPException(
                 status_code=status.HTTP_400_BAD_REQUEST,
@@ -286,7 +358,9 @@ async def _validate_git_mounts(
             )
 
 
-def _profile_to_response(profile: ConfigProfile, includes: list[ConfigProfileInclude] | None = None) -> dict:
+def _profile_to_response(
+    profile: ConfigProfile, includes: list[ConfigProfileInclude] | None = None
+) -> dict:
     return {
         "id": str(profile.id),
         "user_id": str(profile.user_id),
@@ -316,13 +390,19 @@ def _profile_to_response(profile: ConfigProfile, includes: list[ConfigProfileInc
 @router.get("", response_model=list[ConfigProfileResponse])
 async def list_config_profiles(
     project_id: str | None = Query(None, description="Filter by project compatibility"),
-    tool_type_id: str | None = Query(None, description="Filter by tool type compatibility"),
+    tool_type_id: str | None = Query(
+        None, description="Filter by tool type compatibility"
+    ),
     current_user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ):
     """List config profiles, optionally filtered by compatibility."""
     user_uuid = current_user_id
-    query = select(ConfigProfile).where(ConfigProfile.user_id == user_uuid).options(selectinload(ConfigProfile.includes))
+    query = (
+        select(ConfigProfile)
+        .where(ConfigProfile.user_id == user_uuid)
+        .options(selectinload(ConfigProfile.includes))
+    )
 
     if project_id or tool_type_id:
         # Compatibility filter: include portable profiles and matching scoped profiles
@@ -334,7 +414,8 @@ async def list_config_profiles(
         conditions: list = []
         # Portable profiles (no project, no tool)
         conditions.append(
-            (ConfigProfile.project_id.is_(None)) & (ConfigProfile.tool_type_id.is_(None))
+            (ConfigProfile.project_id.is_(None))
+            & (ConfigProfile.tool_type_id.is_(None))
         )
         if project_uuid:
             # Profiles matching this project (with or without tool)
@@ -345,7 +426,8 @@ async def list_config_profiles(
         if project_uuid and tool_uuid:
             # Exact match
             conditions.append(
-                (ConfigProfile.project_id == project_uuid) & (ConfigProfile.tool_type_id == tool_uuid)
+                (ConfigProfile.project_id == project_uuid)
+                & (ConfigProfile.tool_type_id == tool_uuid)
             )
 
         query = query.where(or_(*conditions))
@@ -355,7 +437,9 @@ async def list_config_profiles(
     return [_profile_to_response(p) for p in profiles]
 
 
-@router.post("", response_model=ConfigProfileResponse, status_code=status.HTTP_201_CREATED)
+@router.post(
+    "", response_model=ConfigProfileResponse, status_code=status.HTTP_201_CREATED
+)
 async def create_config_profile(
     data: ConfigProfileCreate,
     current_user_id: uuid.UUID = Depends(get_current_user_id),
@@ -366,10 +450,12 @@ async def create_config_profile(
 
     # Check for duplicate name
     existing = await session.execute(
-        select(ConfigProfile).where(
+        select(ConfigProfile)
+        .where(
             ConfigProfile.user_id == user_uuid,
             ConfigProfile.name == data.name,
-        ).options(selectinload(ConfigProfile.includes))
+        )
+        .options(selectinload(ConfigProfile.includes))
     )
     if existing.scalar_one_or_none() is not None:
         raise HTTPException(
@@ -381,10 +467,12 @@ async def create_config_profile(
     project_uuid = uuid.UUID(data.project_id) if data.project_id else None
     tool_uuid = uuid.UUID(data.tool_type_id) if data.tool_type_id else None
     await _check_access(session, user_uuid, project_uuid, tool_uuid)
-    
+
     # Validate git mounts reference existing repositories
     if data.git_mounts:
-        git_mounts_data = [m.model_dump() if hasattr(m, "model_dump") else m for m in data.git_mounts]
+        git_mounts_data = [
+            m.model_dump() if hasattr(m, "model_dump") else m for m in data.git_mounts
+        ]
         await _validate_git_mounts(session, user_uuid, git_mounts_data, project_uuid)
 
     # Check size
@@ -432,9 +520,13 @@ async def get_config_profile(
     """Get a config profile by ID."""
     profile = await _get_profile_with_includes(session, uuid.UUID(profile_id))
     if profile is None:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Profile not found")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="Profile not found"
+        )
     if profile.user_id != current_user_id:
-        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Not authorized")
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN, detail="Not authorized"
+        )
     return _profile_to_response(profile)
 
 
@@ -448,9 +540,13 @@ async def update_config_profile(
     """Update a config profile."""
     profile = await _get_profile_with_includes(session, uuid.UUID(profile_id))
     if profile is None:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Profile not found")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="Profile not found"
+        )
     if profile.user_id != current_user_id:
-        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Not authorized")
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN, detail="Not authorized"
+        )
 
     update_data = data.model_dump(exclude_unset=True)
 
@@ -481,14 +577,16 @@ async def update_config_profile(
         else (profile.tool_type_id if "tool_type_id" not in update_data else None)
     )
     await _check_access(session, profile.user_id, project_uuid, tool_uuid)
-    
+
     # Validate git mounts reference existing repositories
     if "git_mounts" in update_data and update_data["git_mounts"] is not None:
         git_mounts_data = [
-            m.model_dump() if hasattr(m, "model_dump") else m 
+            m.model_dump() if hasattr(m, "model_dump") else m
             for m in update_data["git_mounts"]
         ]
-        await _validate_git_mounts(session, profile.user_id, git_mounts_data, project_uuid)
+        await _validate_git_mounts(
+            session, profile.user_id, git_mounts_data, project_uuid
+        )
 
     # Check size
     current_data = _profile_to_response(profile)
@@ -533,9 +631,13 @@ async def delete_config_profile(
     """Delete a config profile."""
     profile = await _get_profile_with_includes(session, uuid.UUID(profile_id))
     if profile is None:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Profile not found")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="Profile not found"
+        )
     if profile.user_id != current_user_id:
-        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Not authorized")
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN, detail="Not authorized"
+        )
 
     await session.delete(profile)
     await session.commit()
@@ -554,9 +656,13 @@ async def update_profile_includes(
     """Update the ordered includes for a config profile."""
     profile = await _get_profile_with_includes(session, uuid.UUID(profile_id))
     if profile is None:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Profile not found")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="Profile not found"
+        )
     if profile.user_id != current_user_id:
-        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Not authorized")
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN, detail="Not authorized"
+        )
 
     # Validate all included profiles exist and belong to the user
     included_uuids = [uuid.UUID(inc_id) for inc_id in data.includes]
@@ -596,7 +702,9 @@ async def update_profile_includes(
 
     # Remove existing includes
     result = await session.execute(
-        select(ConfigProfileInclude).where(ConfigProfileInclude.profile_id == profile.id)
+        select(ConfigProfileInclude).where(
+            ConfigProfileInclude.profile_id == profile.id
+        )
     )
     for existing in result.scalars().all():
         await session.delete(existing)
@@ -621,7 +729,9 @@ async def update_profile_includes(
     profile = result.scalar_one()
 
     inc_result = await session.execute(
-        select(ConfigProfileInclude).where(ConfigProfileInclude.profile_id == profile.id)
+        select(ConfigProfileInclude).where(
+            ConfigProfileInclude.profile_id == profile.id
+        )
     )
     direct_includes = inc_result.scalars().all()
 
@@ -638,9 +748,13 @@ async def preview_config_profile(
     """Preview the resolved output of a config profile."""
     profile = await _get_profile_with_includes(session, uuid.UUID(profile_id))
     if profile is None:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Profile not found")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="Profile not found"
+        )
     if profile.user_id != current_user_id:
-        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Not authorized")
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN, detail="Not authorized"
+        )
 
     try:
         resolved = await resolve_profile(session, profile.id)

apps/api/src/api/terminal.py

@@ -1,16 +1,21 @@
 """WebSocket terminal endpoint for tool instances."""
 
 import asyncio
+import json
 import logging
 import uuid
+from contextlib import suppress
 
 from fastapi import APIRouter, Depends, HTTPException, WebSocket, status
+from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
+from starlette.websockets import WebSocketDisconnect
 
-from src.auth.dependencies import get_db_session
+from src.auth.dependencies import get_current_user_id, get_db_session
+from src.models.terminal_session import TerminalSessionModel
 from src.models.tool_instance import ToolInstance
 from src.models.tool_type import ToolType
-from src.services.terminal_manager import terminal_manager
+from src.services.terminal_manager import MaxSessionsExceededError, terminal_manager
 
 router = APIRouter()
 logger = logging.getLogger(__name__)
@@ -19,32 +24,58 @@ logger = logging.getLogger(__name__)
 class SessionRef:
     """Mutable reference to a terminal session, allowing updates during reset."""
 
-    def __init__(self, session):
+    def __init__(self, session, slot_session_id: str | None = None):
         self.session = session
+        self.slot_session_id = slot_session_id or session.session_id
 
 
 @router.websocket(
     "/ws/tool-instances/{instance_id}/terminal",
 )
-async def terminal_websocket(
+async def terminal_websocket_default(
     websocket: WebSocket,
     instance_id: str,
     db_session: AsyncSession = Depends(get_db_session),
 ) -> None:
-    """WebSocket endpoint for terminal access to a tool instance.
+    """WebSocket endpoint for terminal access (default session alias).
 
-    Provides an interactive terminal session inside a running tool instance container.
-    Sessions persist across WebSocket disconnections.
+    Backward-compatible route that maps to the default session.
+    """
+    await _handle_terminal_websocket(websocket, instance_id, None, db_session)
+
+
+@router.websocket(
+    "/ws/tool-instances/{instance_id}/terminal/{session_id}",
+)
+async def terminal_websocket_specific(
+    websocket: WebSocket,
+    instance_id: str,
+    session_id: str,
+    db_session: AsyncSession = Depends(get_db_session),
+) -> None:
+    """WebSocket endpoint for a specific terminal session."""
+    await _handle_terminal_websocket(websocket, instance_id, session_id, db_session)
+
+
+async def _handle_terminal_websocket(
+    websocket: WebSocket,
+    instance_id: str,
+    target_session_id: str | None,
+    db_session: AsyncSession,
+) -> None:
+    """Shared WebSocket handler for terminal sessions.
 
     Args:
         websocket: The WebSocket connection.
         instance_id: UUID string of the tool instance.
+        target_session_id: Specific session ID (slot key). None means default session.
         db_session: Database session.
-
-    Returns:
-        None. Communicates via WebSocket messages.
     """
-    logger.debug("Terminal WebSocket connection attempt for instance %s", instance_id)
+    logger.debug(
+        "Terminal WebSocket connection attempt for instance %s (session=%s)",
+        instance_id,
+        target_session_id or "default",
+    )
     await websocket.accept()
     logger.debug("Terminal WebSocket accepted for instance %s", instance_id)
 
@@ -59,7 +90,9 @@ async def terminal_websocket(
     # Authenticate user from session cookie
     user_id = await _get_user_from_websocket(websocket, db_session)
     if user_id is None:
-        logger.warning("Unauthorized terminal access attempt for instance %s", instance_id)
+        logger.warning(
+            "Unauthorized terminal access attempt for instance %s", instance_id
+        )
         await websocket.close(code=4003, reason="Unauthorized")
         return
 
@@ -71,31 +104,112 @@ async def terminal_websocket(
         return
 
     if instance.owner_id != user_id:
-        logger.warning("Forbidden terminal access for instance %s by user %s", instance_id, user_id)
+        logger.warning(
+            "Forbidden terminal access for instance %s by user %s",
+            instance_id,
+            user_id,
+        )
         await websocket.close(code=4003, reason="Forbidden")
         return
 
     if instance.status != "running" or not instance.container_id:
-        logger.warning("Instance %s not running (status=%s, container_id=%s)", instance_id, instance.status, instance.container_id)
+        logger.warning(
+            "Instance %s not running (status=%s, container_id=%s)",
+            instance_id,
+            instance.status,
+            instance.container_id,
+        )
         await websocket.close(code=4004, reason="Instance not running")
         return
 
     logger.debug("Terminal auth passed for instance %s, user %s", instance_id, user_id)
 
+    # Verify the container actually exists (may have been removed/recreated)
+    from src.services.docker import get_container_status
+
+    container_status = get_container_status(instance.container_id)
+    if container_status["status"] == "not_found":
+        logger.error(
+            "Container %s for instance %s not found (may have been removed)",
+            instance.container_id,
+            instance_id,
+        )
+        await websocket.close(
+            code=4004, reason="Container not found — restart the tool instance"
+        )
+        return
+
     # Fetch tool type to get startup_command
     tool_type = await db_session.get(ToolType, instance.tool_type_id)
     startup_command = tool_type.startup_command if tool_type else None
     if startup_command:
-        logger.debug("Using startup command for instance %s: %s", instance_id, startup_command)
+        logger.debug(
+            "Using startup command for instance %s: %s",
+            instance_id,
+            startup_command,
+        )
+
+    session = None
 
     # Get or create terminal session
     try:
-        session = await terminal_manager.get_or_create_session(
-            instance_uuid,
-            instance.container_id,
-            startup_command=startup_command,
+        if target_session_id is None:
+            # Default session alias
+            session = await terminal_manager.get_or_create_session(
+                instance_uuid,
+                instance.container_id,
+                startup_command=startup_command,
+            )
+            slot_session_id = "default"
+        else:
+            # Specific session
+            session = terminal_manager.get_session(
+                instance_id,
+                target_session_id,
+            )
+            if session is None:
+                # Session not in memory — may have been lost on server restart.
+                # Try to restore from the DB row.
+                db_row = await db_session.get(
+                    TerminalSessionModel, uuid.UUID(target_session_id)
+                )
+                if (
+                    db_row is not None
+                    and db_row.instance_id == instance_uuid
+                    and db_row.status != "closed"
+                ):
+                    logger.info(
+                        "Restoring terminal session %s for instance %s from DB",
+                        target_session_id,
+                        instance_id,
+                    )
+                    session = await terminal_manager.create_session(
+                        instance_uuid,
+                        instance.container_id,
+                        startup_command=startup_command,
+                        name=db_row.name,
+                        session_id=target_session_id,
+                    )
+                else:
+                    logger.warning(
+                        "Session %s not found for instance %s",
+                        target_session_id,
+                        instance_id,
+                    )
+                    await websocket.close(code=4004, reason="Session not found")
+                    return
+            # Determine slot key for reset scoping
+            key = terminal_manager._find_key_by_internal_id(
+                instance_id, session.session_id
+            )
+            slot_session_id = key[1] if key else target_session_id
+
+        logger.debug(
+            "Terminal session ready for instance %s (session_id=%s, slot=%s)",
+            instance_id,
+            session.session_id,
+            slot_session_id,
         )
-        logger.debug("Terminal session ready for instance %s (session_id=%s)", instance_id, session.session_id)
 
         # Attach WebSocket to session
         await terminal_manager.attach_websocket(session, websocket)
@@ -106,11 +220,13 @@ async def terminal_websocket(
         logger.debug("Sent connected status for instance %s", instance_id)
 
         # Use mutable session reference so loops can survive reset
-        session_ref = SessionRef(session)
+        session_ref = SessionRef(session, slot_session_id)
 
         # Start I/O loops and heartbeat
         read_task = asyncio.create_task(_read_loop(session_ref, websocket))
-        write_task = asyncio.create_task(_write_loop(session_ref, websocket, instance_id))
+        write_task = asyncio.create_task(
+            _write_loop(session_ref, websocket, instance_id)
+        )
         heartbeat_task = asyncio.create_task(_heartbeat_loop(websocket))
         logger.debug("Started terminal loops for instance %s", instance_id)
 
@@ -119,24 +235,36 @@ async def terminal_websocket(
             [read_task, write_task, heartbeat_task],
             return_when=asyncio.FIRST_COMPLETED,
         )
-        
-        logger.debug("Terminal loop completed for instance %s, done=%s", instance_id, len(done))
-        
+
+        logger.debug(
+            "Terminal loop completed for instance %s, done=%s",
+            instance_id,
+            len(done),
+        )
+
         # Cancel remaining tasks
         for task in pending:
             task.cancel()
 
+    except WebSocketDisconnect:
+        logger.debug("WebSocket disconnected for instance %s", instance_id)
     except Exception as exc:
-        logger.error("Terminal session error for instance %s: %s", instance_id, str(exc), exc_info=True)
-        await websocket.close(code=4000, reason=f"Error: {exc}")
+        logger.error(
+            "Terminal session error for instance %s: %s",
+            instance_id,
+            str(exc),
+            exc_info=True,
+        )
+        with suppress(Exception):
+            await websocket.close(code=4000, reason=f"Error: {exc}")
     finally:
         # Detach WebSocket, don't kill session
-        try:
-            if 'session' in locals():
+        with suppress(Exception):
+            if session is not None:
                 await terminal_manager.detach_websocket(session, websocket)
-                logger.debug("WebSocket detached from session for instance %s", instance_id)
-        except Exception:
-            pass
+                logger.debug(
+                    "WebSocket detached from session for instance %s", instance_id
+                )
 
 
 async def _read_loop(session_ref: SessionRef, websocket) -> None:
@@ -151,6 +279,8 @@ async def _read_loop(session_ref: SessionRef, websocket) -> None:
             if data:
                 try:
                     await websocket.send_bytes(data)
+                except WebSocketDisconnect:
+                    break
                 except Exception:
                     break
             else:
@@ -175,38 +305,54 @@ async def _write_loop(session_ref: SessionRef, websocket, instance_id: str) -> N
                     text = message["text"]
                     if text.startswith("{"):
                         # Control message (JSON)
-                        import json
                         try:
                             ctrl = json.loads(text)
                             msg_type = ctrl.get("type")
-                            
+
                             if msg_type == "resize":
                                 cols = ctrl.get("cols", 80)
                                 rows = ctrl.get("rows", 24)
-                                logger.debug(f"Received resize message for instance {instance_id}: {cols}x{rows}")
+                                logger.debug(
+                                    "Received resize message for instance %s: %sx%s",
+                                    instance_id,
+                                    cols,
+                                    rows,
+                                )
                                 await session.resize(cols, rows)
                             elif msg_type == "reset":
-                                # Reset terminal session
-                                logger.debug("Resetting terminal session for instance %s", session.instance_id)
-                                await websocket.send_json({"type": "status", "status": "resetting"})
-                                
-                                # Reset the session
+                                # Reset terminal session (scoped to current slot)
+                                logger.debug(
+                                    "Resetting terminal session for instance %s (slot=%s)",
+                                    session.instance_id,
+                                    session_ref.slot_session_id,
+                                )
+                                await websocket.send_json(
+                                    {"type": "status", "status": "resetting"}
+                                )
+
+                                # Reset the session scoped to its slot
                                 new_session = await terminal_manager.reset_session(
                                     session.instance_id,
                                     session.container_id,
                                     startup_command=session.startup_command,
+                                    session_id=session_ref.slot_session_id,
+                                    name=session.name,
                                 )
-                                
-                                # Update the mutable session reference so read_loop uses the new session
+
+                                # Update the mutable session reference
                                 session_ref.session = new_session
-                                
+
                                 # Attach to new session
-                                await terminal_manager.attach_websocket(new_session, websocket)
-                                await websocket.send_json({"type": "status", "status": "connected"})
-                                
+                                await terminal_manager.attach_websocket(
+                                    new_session, websocket
+                                )
+                                await websocket.send_json(
+                                    {"type": "status", "status": "connected"}
+                                )
+
                                 # Continue the loop with the new session
                                 continue
-                                
+
                         except json.JSONDecodeError:
                             # Not a valid JSON control message, treat as regular input
                             await session.write_input(text.encode("utf-8"))
@@ -232,56 +378,349 @@ async def _heartbeat_loop(websocket: WebSocket) -> None:
         pass
 
 
-@router.post(
-    "/projects/{project_id}/repositories/{repo_id}/instances/{instance_id}/terminal/reset",
-    summary="Reset terminal session",
-    description="Reset the terminal session for a tool instance, killing the current shell and starting fresh.",
-)
-async def reset_terminal_session(
-    project_id: uuid.UUID,
-    repo_id: uuid.UUID,
+async def _get_terminal_instance(
     instance_id: uuid.UUID,
-    db_session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    """Reset the terminal session for an instance.
+    user_id: uuid.UUID,
+    db_session: AsyncSession,
+) -> ToolInstance:
+    """Fetch instance and validate auth, ownership, and running status.
 
     Args:
-        project_id: UUID of the project.
-        repo_id: UUID of the repository.
         instance_id: UUID of the tool instance.
+        user_id: ID of the authenticated user.
         db_session: Database session.
 
     Returns:
-        Dictionary with status message.
+        The validated ToolInstance.
+
+    Raises:
+        HTTPException: If instance not found, not owned, or not running.
     """
-    # Get instance and verify it exists and is running
     instance = await db_session.get(ToolInstance, instance_id)
     if instance is None:
         raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail="Instance not found"
+            status_code=status.HTTP_404_NOT_FOUND, detail="Instance not found"
+        )
+
+    if instance.owner_id != user_id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Not authorized to access this instance",
         )
 
     if instance.status != "running" or not instance.container_id:
         raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail="Instance is not running"
+            status_code=status.HTTP_400_BAD_REQUEST, detail="Instance is not running"
+        )
+
+    return instance
+
+
+@router.get(
+    "/instances/{instance_id}/terminal/sessions",
+    summary="List terminal sessions",
+    description="List terminal sessions for a tool instance with live WebSocket state.",
+)
+async def list_terminal_sessions(
+    instance_id: uuid.UUID,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    db_session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """List terminal sessions for an instance.
+
+    Args:
+        instance_id: UUID of the tool instance.
+        user_id: ID of the authenticated user.
+        db_session: Database session.
+
+    Returns:
+        Dictionary with sessions list.
+    """
+    await _get_terminal_instance(instance_id, user_id, db_session)
+
+    # Query active DB rows for this instance
+    result = await db_session.execute(
+        select(TerminalSessionModel)
+        .where(TerminalSessionModel.instance_id == instance_id)
+        .where(TerminalSessionModel.status != "closed")
+        .order_by(TerminalSessionModel.created_at.asc())
+    )
+    db_rows = result.scalars().all()
+
+    # Build response with live has_websockets flag.
+    # Include DB rows even without in-memory counterparts (e.g. after
+    # server restart) so the frontend can display tabs and reconnect.
+    sessions = []
+    for row in db_rows:
+        live_session = terminal_manager.get_session(str(instance_id), str(row.id))
+        sessions.append(
+            {
+                "id": str(row.id),
+                "name": row.name,
+                "status": row.status,
+                "has_websockets": live_session.has_websockets()
+                if live_session
+                else False,
+                "created_at": row.created_at.isoformat() if row.created_at else None,
+                "last_activity_at": row.last_activity_at.isoformat()
+                if row.last_activity_at
+                else None,
+            }
+        )
+
+    return {"sessions": sessions}
+
+
+@router.post(
+    "/instances/{instance_id}/terminal/sessions",
+    summary="Create terminal session",
+    description="Create a new terminal session for a running tool instance.",
+    status_code=status.HTTP_201_CREATED,
+)
+async def create_terminal_session(
+    instance_id: uuid.UUID,
+    data: dict,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    db_session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Create a new terminal session.
+
+    Args:
+        instance_id: UUID of the tool instance.
+        data: Request body with optional name.
+        user_id: ID of the authenticated user.
+        db_session: Database session.
+
+    Returns:
+        Dictionary with new session details.
+
+    Raises:
+        HTTPException: 409 if max sessions reached.
+    """
+    instance = await _get_terminal_instance(instance_id, user_id, db_session)
+    assert instance.container_id is not None
+
+    # Fetch tool type to get startup_command
+    tool_type = await db_session.get(ToolType, instance.tool_type_id)
+    startup_command = tool_type.startup_command if tool_type else None
+
+    name = data.get("name")
+
+    try:
+        session = await terminal_manager.create_session(
+            instance_id,
+            instance.container_id,
+            startup_command=startup_command,
+            name=name,
+        )
+    except MaxSessionsExceededError:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail="Maximum of 5 terminal sessions reached for this instance",
+        ) from None
+
+    return {
+        "id": session.session_id,
+        "name": session.name,
+        "status": session.status,
+        "created_at": session.last_activity,
+    }
+
+
+@router.delete(
+    "/instances/{instance_id}/terminal/sessions/{session_id}",
+    summary="Close terminal session",
+    description="Close a specific terminal session.",
+)
+async def close_terminal_session(
+    instance_id: uuid.UUID,
+    session_id: str,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    db_session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Close a terminal session.
+
+    Args:
+        instance_id: UUID of the tool instance.
+        session_id: ID of the session to close.
+        user_id: ID of the authenticated user.
+        db_session: Database session.
+
+    Returns:
+        Dictionary with closure status.
+    """
+    await _get_terminal_instance(instance_id, user_id, db_session)
+
+    # Find the session by internal ID to determine its slot key
+    key = terminal_manager._find_key_by_internal_id(str(instance_id), session_id)
+    if (
+        key is None
+        and terminal_manager.get_session(str(instance_id), session_id) is not None
+    ):
+        key = (str(instance_id), session_id)
+
+    if key is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="Session not found"
+        )
+
+    await terminal_manager.close_session(key[0], key[1])
+
+    return {"status": "closed", "session_id": session_id}
+
+
+@router.post(
+    "/instances/{instance_id}/terminal/sessions/{session_id}/reset",
+    summary="Reset terminal session",
+    description="Reset a specific terminal session, killing the current shell and starting fresh.",
+)
+async def reset_specific_terminal_session(
+    instance_id: uuid.UUID,
+    session_id: str,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    db_session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Reset a specific terminal session.
+
+    Args:
+        instance_id: UUID of the tool instance.
+        session_id: ID of the session to reset.
+        user_id: ID of the authenticated user.
+        db_session: Database session.
+
+    Returns:
+        Dictionary with reset session details.
+    """
+    instance = await _get_terminal_instance(instance_id, user_id, db_session)
+    assert instance.container_id is not None
+
+    # Determine slot key for reset
+    key = terminal_manager._find_key_by_internal_id(str(instance_id), session_id)
+    if (
+        key is None
+        and terminal_manager.get_session(str(instance_id), session_id) is not None
+    ):
+        key = (str(instance_id), session_id)
+
+    if key is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="Session not found"
         )
 
     # Fetch tool type to get startup_command
     tool_type = await db_session.get(ToolType, instance.tool_type_id)
     startup_command = tool_type.startup_command if tool_type else None
 
+    # Preserve name if possible
+    live_session = terminal_manager.get_session(str(instance_id), session_id)
+    name = live_session.name if live_session else None
+
+    new_session = await terminal_manager.reset_session(
+        instance_id,
+        instance.container_id,
+        startup_command=startup_command,
+        session_id=key[1],
+        name=name,
+    )
+
+    return {
+        "id": new_session.session_id,
+        "name": new_session.name,
+        "status": new_session.status,
+    }
+
+
+@router.post(
+    "/instances/{instance_id}/terminal/sessions/{session_id}/rename",
+    summary="Rename terminal session",
+    description="Rename a specific terminal session.",
+)
+async def rename_terminal_session(
+    instance_id: uuid.UUID,
+    session_id: str,
+    data: dict,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    db_session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Rename a terminal session.
+
+    Args:
+        instance_id: UUID of the tool instance.
+        session_id: ID of the session to rename.
+        data: Request body with new name.
+        user_id: ID of the authenticated user.
+        db_session: Database session.
+
+    Returns:
+        Dictionary with updated session details.
+    """
+    await _get_terminal_instance(instance_id, user_id, db_session)
+
+    new_name = data.get("name")
+    if not new_name or not isinstance(new_name, str):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST, detail="Name is required"
+        )
+
+    # Update in-memory session name if live
+    live_session = terminal_manager.get_session(str(instance_id), session_id)
+    if live_session:
+        live_session.name = new_name
+
+    # Update DB row
+    db_row = await db_session.get(TerminalSessionModel, uuid.UUID(session_id))
+    if db_row is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="Session not found"
+        )
+
+    db_row.name = new_name
+    await db_session.commit()
+
+    return {"id": str(db_row.id), "name": new_name}
+
+
+@router.post(
+    "/instances/{instance_id}/terminal/reset",
+    summary="Reset terminal session (legacy alias)",
+    description="Reset the default terminal session for a tool instance. Preserved for backward compatibility.",
+)
+async def reset_terminal_session(
+    instance_id: uuid.UUID,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    db_session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Reset the default terminal session for an instance (legacy alias).
+
+    Args:
+        instance_id: UUID of the tool instance.
+        user_id: ID of the authenticated user.
+        db_session: Database session.
+
+    Returns:
+        Dictionary with status message.
+    """
+    instance = await _get_terminal_instance(instance_id, user_id, db_session)
+    assert instance.container_id is not None
+
+    # Fetch tool type to get startup_command
+    tool_type = await db_session.get(ToolType, instance.tool_type_id)
+    startup_command = tool_type.startup_command if tool_type else None
+
     try:
-        # Reset the session
+        # Reset the default session
         new_session = await terminal_manager.reset_session(
             instance_id,
             instance.container_id,
             startup_command=startup_command,
         )
-        
-        logger.info("Terminal session reset for instance %s (new session_id=%s)", instance_id, new_session.session_id)
-        
+
+        logger.info(
+            "Terminal session reset for instance %s (new session_id=%s)",
+            instance_id,
+            new_session.session_id,
+        )
+
         return {
             "status": "success",
             "message": "Terminal session reset successfully",
@@ -289,11 +728,16 @@ async def reset_terminal_session(
             "session_id": new_session.session_id,
         }
     except Exception as exc:
-        logger.error("Failed to reset terminal session for instance %s: %s", instance_id, str(exc), exc_info=True)
+        logger.error(
+            "Failed to reset terminal session for instance %s: %s",
+            instance_id,
+            str(exc),
+            exc_info=True,
+        )
         raise HTTPException(
             status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"Failed to reset terminal session: {exc}"
-        )
+            detail=f"Failed to reset terminal session: {exc}",
+        ) from exc
 
 
 async def _get_user_from_websocket(

apps/api/src/api/tool_configs.py

@@ -1,290 +0,0 @@
-"""Tool configuration API endpoints."""
-
-import uuid
-
-from fastapi import APIRouter, Depends, HTTPException, status
-from pydantic import BaseModel, Field, field_validator
-from sqlalchemy import select
-from sqlalchemy.ext.asyncio import AsyncSession
-
-from src.api.shared_validators import validate_env_vars as _validate_env_vars, validate_volumes as _validate_volumes
-from src.auth.dependencies import get_current_user_id, get_db_session
-from src.models.tool_config import ToolConfig
-from src.models.tool_type import ToolType
-
-router = APIRouter(prefix="/tool-configs", tags=["tool-configs"])
-
-
-class ToolConfigCreate(BaseModel):
-    tool_type_id: str = Field(description="UUID of the tool type")
-    project_id: str | None = Field(default=None, description="Optional project ID for project-scoped config")
-    key: str = Field(description="Config key name")
-    value: str = Field(description="Config value")
-    config_type: str = Field(default="env", description="Type: env or file")
-    file_path: str | None = Field(default=None, description="File path for file-type configs")
-    port_override: int | None = Field(default=None, description="Port override (1-65535)")
-    start_command: str | None = Field(default=None, description="Override container start command")
-    working_directory: str | None = Field(default=None, description="Working directory inside container")
-    environment_variables: dict | None = Field(default=None, description="Environment variables as JSON object")
-    volumes: list[dict] | None = Field(default=None, description="Volume mounts as JSON array")
-
-    @field_validator("port_override")
-    @classmethod
-    def validate_port(cls, v: int | None) -> int | None:
-        if v is None:
-            return v
-        if v < 1 or v > 65535:
-            raise ValueError("Port must be between 1 and 65535")
-        return v
-
-    @field_validator("environment_variables")
-    @classmethod
-    def validate_env_vars(cls, v: dict | None) -> dict | None:
-        return _validate_env_vars(v)
-
-    @field_validator("volumes")
-    @classmethod
-    def validate_volumes(cls, v: list | None) -> list | None:
-        return _validate_volumes(v)
-
-
-class ToolConfigUpdate(BaseModel):
-    key: str | None = Field(default=None, description="Config key name")
-    value: str | None = Field(default=None, description="Config value")
-    config_type: str | None = Field(default=None, description="Type: env or file")
-    file_path: str | None = Field(default=None, description="File path for file-type configs")
-    port_override: int | None = Field(default=None, description="Port override (1-65535)")
-    start_command: str | None = Field(default=None, description="Override container start command")
-    working_directory: str | None = Field(default=None, description="Working directory inside container")
-    environment_variables: dict | None = Field(default=None, description="Environment variables as JSON object")
-    volumes: list[dict] | None = Field(default=None, description="Volume mounts as JSON array")
-
-    @field_validator("port_override")
-    @classmethod
-    def validate_port(cls, v: int | None) -> int | None:
-        if v is None:
-            return v
-        if v < 1 or v > 65535:
-            raise ValueError("Port must be between 1 and 65535")
-        return v
-
-    @field_validator("environment_variables")
-    @classmethod
-    def validate_env_vars(cls, v: dict | None) -> dict | None:
-        return _validate_env_vars(v)
-
-    @field_validator("volumes")
-    @classmethod
-    def validate_volumes(cls, v: list | None) -> list | None:
-        return _validate_volumes(v)
-
-
-class ToolConfigResponse(BaseModel):
-    id: str
-    tool_type_id: str
-    project_id: str | None
-    key: str
-    value: str
-    config_type: str
-    file_path: str | None
-    port_override: int | None
-    start_command: str | None
-    working_directory: str | None
-    environment_variables: dict | None
-    volumes: list[dict] | None
-
-
-@router.get("", summary="List tool configs", description="Get all tool configs for the current user.")
-async def list_configs(
-    tool_type_id: str | None = None,
-    project_id: str | None = None,
-    user_id: uuid.UUID = Depends(get_current_user_id),
-    session: AsyncSession = Depends(get_db_session),
-) -> list:
-    """List tool configs for the current user."""
-    query = select(ToolConfig).where(ToolConfig.user_id == user_id)
-    
-    if tool_type_id:
-        query = query.where(ToolConfig.tool_type_id == uuid.UUID(tool_type_id))
-    if project_id:
-        query = query.where(ToolConfig.project_id == uuid.UUID(project_id))
-    else:
-        # If no project specified, get only global configs (project_id is None)
-        query = query.where(ToolConfig.project_id.is_(None))
-    
-    result = await session.execute(query)
-    configs = result.scalars().all()
-    
-    return [
-        {
-            "id": str(c.id),
-            "tool_type_id": str(c.tool_type_id),
-            "project_id": str(c.project_id) if c.project_id else None,
-            "key": c.key,
-            "value": c.value,
-            "config_type": c.config_type,
-            "file_path": c.file_path,
-            "port_override": c.port_override,
-            "start_command": c.start_command,
-            "working_directory": c.working_directory,
-            "environment_variables": c.environment_variables,
-            "volumes": c.volumes,
-        }
-        for c in configs
-    ]
-
-
-@router.post("", summary="Create tool config", description="Create a new tool config.", status_code=status.HTTP_201_CREATED)
-async def create_config(
-    data: ToolConfigCreate,
-    user_id: uuid.UUID = Depends(get_current_user_id),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    """Create a tool config."""
-    # Verify tool type exists
-    tool_type = await session.get(ToolType, uuid.UUID(data.tool_type_id))
-    if tool_type is None:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="tool type not found")
-    
-    # Check for existing config with same key
-    query = select(ToolConfig).where(
-        ToolConfig.user_id == user_id,
-        ToolConfig.tool_type_id == uuid.UUID(data.tool_type_id),
-        ToolConfig.key == data.key,
-    )
-    if data.project_id:
-        query = query.where(ToolConfig.project_id == uuid.UUID(data.project_id))
-    else:
-        query = query.where(ToolConfig.project_id.is_(None))
-    
-    existing = await session.scalar(query)
-    if existing:
-        raise HTTPException(
-            status_code=status.HTTP_409_CONFLICT,
-            detail=f"config with key '{data.key}' already exists"
-        )
-    
-    config = ToolConfig(
-        user_id=user_id,
-        tool_type_id=uuid.UUID(data.tool_type_id),
-        project_id=uuid.UUID(data.project_id) if data.project_id else None,
-        key=data.key,
-        value=data.value,
-        config_type=data.config_type,
-        file_path=data.file_path,
-        port_override=data.port_override,
-        start_command=data.start_command,
-        working_directory=data.working_directory,
-        environment_variables=data.environment_variables,
-        volumes=data.volumes,
-    )
-    session.add(config)
-    await session.commit()
-    await session.refresh(config)
-    
-    return {
-        "id": str(config.id),
-        "tool_type_id": str(config.tool_type_id),
-        "project_id": str(config.project_id) if config.project_id else None,
-        "key": config.key,
-        "value": config.value,
-        "config_type": config.config_type,
-        "file_path": config.file_path,
-        "port_override": config.port_override,
-        "start_command": config.start_command,
-        "working_directory": config.working_directory,
-        "environment_variables": config.environment_variables,
-        "volumes": config.volumes,
-    }
-
-
-@router.put("/{config_id}", summary="Update tool config", description="Update an existing tool config.")
-async def update_config(
-    config_id: uuid.UUID,
-    data: ToolConfigUpdate,
-    user_id: uuid.UUID = Depends(get_current_user_id),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    """Update a tool config."""
-    config = await session.get(ToolConfig, config_id)
-    if config is None or config.user_id != user_id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="config not found")
-    
-    if data.key is not None:
-        config.key = data.key
-    if data.value is not None:
-        config.value = data.value
-    if data.config_type is not None:
-        config.config_type = data.config_type
-    if data.file_path is not None:
-        config.file_path = data.file_path
-    if data.port_override is not None:
-        config.port_override = data.port_override
-    if data.start_command is not None:
-        config.start_command = data.start_command
-    if data.working_directory is not None:
-        config.working_directory = data.working_directory
-    if data.environment_variables is not None:
-        config.environment_variables = data.environment_variables
-    if data.volumes is not None:
-        config.volumes = data.volumes
-    
-    await session.commit()
-    await session.refresh(config)
-    
-    return {
-        "id": str(config.id),
-        "tool_type_id": str(config.tool_type_id),
-        "project_id": str(config.project_id) if config.project_id else None,
-        "key": config.key,
-        "value": config.value,
-        "config_type": config.config_type,
-        "file_path": config.file_path,
-        "port_override": config.port_override,
-        "start_command": config.start_command,
-        "working_directory": config.working_directory,
-        "environment_variables": config.environment_variables,
-        "volumes": config.volumes,
-    }
-
-
-@router.get("/defaults/{tool_type_id}", summary="Get default configs", description="Get suggested default configs for a tool type.")
-async def get_default_configs(
-    tool_type_id: str,
-    user_id: uuid.UUID = Depends(get_current_user_id),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    """Get suggested default configs for a tool type."""
-    tool_type = await session.get(ToolType, uuid.UUID(tool_type_id))
-    if tool_type is None:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="tool type not found")
-    
-    # Return suggested defaults based on required_variables
-    defaults = []
-    for var in tool_type.required_variables:
-        defaults.append({
-            "key": var,
-            "value": "",
-            "config_type": "env",
-            "description": f"Required variable: {var}",
-        })
-    
-    return {
-        "tool_type_id": tool_type_id,
-        "suggested_configs": defaults,
-    }
-
-
-@router.delete("/{config_id}", summary="Delete tool config", description="Delete a tool config.")
-async def delete_config(
-    config_id: uuid.UUID,
-    user_id: uuid.UUID = Depends(get_current_user_id),
-    session: AsyncSession = Depends(get_db_session),
-) -> None:
-    """Delete a tool config."""
-    config = await session.get(ToolConfig, config_id)
-    if config is None or config.user_id != user_id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="config not found")
-    
-    await session.delete(config)
-    await session.commit()

apps/api/src/api/tool_instances.py

@@ -32,7 +32,6 @@ from src.models.config_profile import ConfigProfile
 from src.models.git_repository import GitRepository
 from src.models.project import Project
 from src.models.ssh_key import SSHKey
-from src.models.tool_config import ToolConfig
 from src.models.tool_instance import ToolInstance
 from src.models.tool_type import ToolType
 from src.services.clone import check_dirty_state, clone_repository
@@ -40,6 +39,7 @@ from src.services.config_profile_resolver import (
     ConfigProfileCycleError,
     ResolvedProfile,
     apply_resolved_profile,
+    expand_container_path,
     resolve_profile,
 )
 from src.services.docker import (
@@ -68,6 +68,7 @@ from src.services.manifest_compiler import (
     compile_entrypoint,
     compute_image_tag,
     deep_merge,
+    get_manifest_home_dir,
     merge_with_config,
     resolve_base,
 )
@@ -83,6 +84,7 @@ async def _resolve_git_mounts(
     resolved: ResolvedProfile,
     instance_dir: str | None = None,
     working_directory: str | None = None,
+    home_dir: str = "/root",
 ) -> list[dict]:
     """Convert git mounts from resolved profile to Docker volume mounts.
 
@@ -98,7 +100,7 @@ async def _resolve_git_mounts(
     for git_mount in resolved.git_mounts:
         tasks.append(
             _resolve_single_git_mount(
-                session, git_mount, instance_dir, working_directory
+                session, git_mount, instance_dir, working_directory, home_dir
             )
         )
 
@@ -115,77 +117,62 @@ async def _resolve_git_mounts(
     return volume_mounts
 
 
-async def _resolve_single_git_mount(
-    session: AsyncSession,
-    git_mount: dict,
-    instance_dir: str | None = None,
-    working_directory: str | None = None,
-) -> list[dict]:
-    """Resolve a single git mount to volume mount entries.
+def _normalize_git_mount(entry: dict) -> dict:
+    """Normalize a git mount entry to the unified mappings format.
 
-    Clones directly from remote_url, no database lookup needed.
-    Returns a list of volume mounts (one for each matched file/directory).
+    Converts legacy source_path + target_path into a single-entry mappings array.
     """
-    remote_url = git_mount.get("remote_url")
-    source_path = git_mount.get("source_path", ".")
-    target_path = git_mount.get("target_path")
-    branch = git_mount.get("branch")
+    entry = dict(entry)
+    if "mappings" not in entry or not entry.get("mappings"):
+        source = entry.get("source_path", ".")
+        target = entry.get("target_path")
+        if target is not None:
+            entry["mappings"] = [{"source_path": source, "target_path": target}]
+    entry.pop("source_path", None)
+    entry.pop("target_path", None)
+    return entry
 
-    if not remote_url or not target_path:
-        logger.warning("Invalid git mount skipped: missing remote_url or target_path")
-        return []
 
-    # Resolve relative target paths against working directory
-    if target_path and not target_path.startswith("/"):
-        if not working_directory:
-            logger.warning(
-                "Git mount skipped: target_path '%s' is relative but no working_directory is configured. "
-                "Set working_directory in the tool config or use an absolute path.",
-                target_path,
-            )
-            return []
-        target_path = os.path.join(working_directory, target_path)
-        logger.debug("Resolved relative target path to %s", target_path)
+def _clone_git_repo(
+    remote_url: str,
+    branch: str | None,
+    clone_parent: str,
+) -> str:
+    """Clone or pull a git repository.
 
-    if not instance_dir:
-        logger.warning("Git mount skipped: no instance_dir provided for cloning")
-        return []
-
-    # Generate a unique directory name from the URL
+    Returns the path to the cloned repo (repo-clone directory).
+    """
     import hashlib
 
     url_hash = hashlib.md5(remote_url.encode()).hexdigest()[:12]
     repo_name = remote_url.split("/")[-1].replace(".git", "") or "repo"
-    clone_parent = os.path.join(instance_dir, "git-mounts", f"{repo_name}-{url_hash}")
-    # clone_repository always creates 'repo-clone' inside the given directory
-    repo_path = os.path.join(clone_parent, "repo-clone")
+    clone_dir = os.path.join(clone_parent, "git-mounts", f"{repo_name}-{url_hash}")
+    repo_path = os.path.join(clone_dir, "repo-clone")
 
-    # Clone or pull the repository
     if not os.path.exists(repo_path):
         try:
-            os.makedirs(clone_parent, exist_ok=True)
-            repo_path = await asyncio.to_thread(
-                clone_repository,
+            os.makedirs(clone_dir, exist_ok=True)
+            repo_path = clone_repository(
                 remote_url,
                 None,  # No SSH key for now - can be added later
-                clone_parent,
+                clone_dir,
                 branch or "main",
             )
             logger.debug("Cloned git mount repository %s to %s", remote_url, repo_path)
         except Exception as exc:
             logger.warning("Clone failed for git mount %s: %s", remote_url, exc)
-            return []
+            raise
     else:
         # Repo exists - pull latest updates
         try:
-            await asyncio.to_thread(_pull_repository_updates, repo_path, remote_url)
+            _pull_repository_updates(repo_path, remote_url)
             logger.debug("Pulled updates for git mount %s", remote_url)
         except Exception as exc:
             logger.warning("Failed to pull updates for %s: %s", remote_url, exc)
 
     # Handle branch checkout if specified
     if branch and repo_path:
-        success = await asyncio.to_thread(_checkout_branch, repo_path, branch)
+        success = _checkout_branch(repo_path, branch)
         if success:
             logger.debug("Checked out branch %s for %s", branch, remote_url)
         else:
@@ -193,54 +180,130 @@ async def _resolve_single_git_mount(
                 "Branch %s not found in %s, using current branch", branch, remote_url
             )
 
-    # Build source path and expand globs
-    if source_path and source_path != ".":
-        source_full = os.path.join(repo_path, source_path)
-    else:
-        source_full = repo_path
+    return repo_path
 
-    # Expand glob patterns
-    matched_paths = _expand_glob_source(source_full, repo_path)
 
-    if not matched_paths:
-        logger.warning(
-            "Git mount skipped: no files matched source path %s in %s",
-            source_path,
-            remote_url,
-        )
-        return []
+def _resolve_git_mount_mappings(
+    repo_path: str,
+    mappings: list[dict],
+    working_directory: str | None,
+    home_dir: str = "/root",
+) -> list[dict]:
+    """Resolve mappings from an already-cloned repo to volume mount entries.
 
+    Returns a flat list of volume mount dicts.
+    """
     volume_mounts = []
-    for matched_path in matched_paths:
-        if not os.path.exists(matched_path):
+
+    for mapping in mappings:
+        source_path = mapping.get("source_path", ".")
+        target_path = mapping.get("target_path")
+
+        if not target_path:
+            logger.warning("Invalid mapping skipped: missing target_path")
             continue
 
-        # Determine target path for this match
-        if len(matched_paths) == 1:
-            # Single match: mount directly to target_path
-            final_target = target_path
-        else:
-            # Multiple matches: append relative path to target
-            rel_path = os.path.relpath(matched_path, repo_path)
-            final_target = os.path.join(target_path, rel_path)
+        # Expand ~ and $HOME in target path
+        target_path = expand_container_path(target_path, home_dir)
 
-        volume_mounts.append(
-            {
-                "source": matched_path,
-                "target": final_target,
-                "type": "bind",
-            }
-        )
-        logger.debug(
-            "Added git mount: %s -> %s (url: %s)",
-            matched_path,
-            final_target,
-            remote_url,
-        )
+        # Resolve relative target paths against working directory
+        final_target = target_path
+        if not target_path.startswith("/"):
+            if not working_directory:
+                logger.warning(
+                    "Git mount skipped: target_path '%s' is relative but no working_directory is configured. "
+                    "Set working_directory in the tool config or use an absolute path.",
+                    target_path,
+                )
+                continue
+            final_target = os.path.join(working_directory, target_path)
+
+        # Build source path and expand globs
+        if source_path and source_path != ".":
+            source_full = os.path.join(repo_path, source_path)
+        else:
+            source_full = repo_path
+
+        # Expand glob patterns
+        matched_paths = _expand_glob_source(source_full, repo_path)
+
+        if not matched_paths:
+            logger.warning(
+                "Git mount skipped: no files matched source path %s in repo",
+                source_path,
+            )
+            continue
+
+        for matched_path in matched_paths:
+            if not os.path.exists(matched_path):
+                continue
+
+            # Determine target path for this match
+            if len(matched_paths) == 1:
+                # Single match: mount directly to target_path
+                mount_target = final_target
+            else:
+                # Multiple matches: append relative path to target
+                rel_path = os.path.relpath(matched_path, repo_path)
+                mount_target = os.path.join(final_target, rel_path)
+
+            volume_mounts.append(
+                {
+                    "source": matched_path,
+                    "target": mount_target,
+                    "type": "bind",
+                }
+            )
+            logger.debug(
+                "Added git mount: %s -> %s",
+                matched_path,
+                mount_target,
+            )
 
     return volume_mounts
 
 
+async def _resolve_single_git_mount(
+    session: AsyncSession,
+    git_mount: dict,
+    instance_dir: str | None = None,
+    working_directory: str | None = None,
+    home_dir: str = "/root",
+) -> list[dict]:
+    """Resolve a single git mount to volume mount entries.
+
+    Clones directly from remote_url, no database lookup needed.
+    Returns a list of volume mounts (one for each matched file/directory).
+    """
+    git_mount = _normalize_git_mount(git_mount)
+    remote_url = git_mount.get("remote_url")
+    branch = git_mount.get("branch")
+    mappings = git_mount.get("mappings", [])
+
+    if not remote_url:
+        logger.warning("Invalid git mount skipped: missing remote_url")
+        return []
+
+    if not mappings:
+        logger.warning("Invalid git mount skipped: no mappings")
+        return []
+
+    if not instance_dir:
+        logger.warning("Git mount skipped: no instance_dir provided for cloning")
+        return []
+
+    # Clone or pull the repository
+    try:
+        repo_path = await asyncio.to_thread(
+            _clone_git_repo, remote_url, branch, instance_dir
+        )
+    except Exception:
+        return []
+
+    # Resolve all mappings from the cloned repo
+    return _resolve_git_mount_mappings(repo_path, mappings, working_directory, home_dir)
+
+
 def _checkout_branch(repo_path: str, branch: str) -> bool:
     """Checkout a specific branch in a git repository.
 
@@ -490,6 +553,7 @@ def _modify_compose_file(
     start_command: str | None = None,
     working_directory: str | None = None,
     extra_volumes: list[dict] | None = None,
+    home_dir: str = "/root",
 ) -> None:
     """Modify compose file with runtime overrides."""
     import yaml
@@ -516,14 +580,16 @@ def _modify_compose_file(
             service_config["command"] = start_command
 
         if working_directory:
-            service_config["working_dir"] = working_directory
+            service_config["working_dir"] = expand_container_path(
+                working_directory, home_dir
+            )
 
         if extra_volumes:
             if "volumes" not in service_config:
                 service_config["volumes"] = []
             for vol in extra_volumes:
                 source = vol.get("source", "")
-                target = vol.get("target", "")
+                target = expand_container_path(vol.get("target", ""), home_dir)
                 vol_type = vol.get("type", "bind")
                 if vol_type == "bind":
                     service_config["volumes"].append(f"{source}:{target}")
@@ -748,8 +814,82 @@ services:
 """
             write_compose_file(instance_dir, compose_content)
 
+        elif tool_type.definition_type == "manifest":
+            # Manifest-based: build image and generate compose
+            from src.models.tool_definition_manifest import ToolDefinitionManifest
+
+            manifest_def = await session.get(
+                ToolDefinitionManifest, tool_type.manifest_id
+            )
+            if not manifest_def:
+                raise HTTPException(
+                    status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                    detail="Manifest definition not found for this tool type",
+                )
+
+            manifest = dict(manifest_def.manifest)
+            if manifest_def.base_definition_id:
+                base_def = await session.get(
+                    ToolDefinitionManifest, manifest_def.base_definition_id
+                )
+                if base_def:
+                    manifest = resolve_base(
+                        deep_merge(dict(base_def.manifest), manifest)
+                    )
+
+            # Determine home directory for path expansion
+            home_dir = get_manifest_home_dir(manifest)
+
+            image_tag = compute_image_tag(tool_type.name, manifest)
+
+            # Build image during creation so start is fast
+            dockerfile = compile_dockerfile(manifest)
+            entrypoint = compile_entrypoint(manifest)
+            build_ctx = {
+                "Dockerfile": dockerfile,
+                ".headquarter/entrypoint.sh": entrypoint,
+            }
+
+            returncode, stdout, stderr = await asyncio.to_thread(
+                build_image,
+                instance_dir=instance_dir,
+                dockerfile=dockerfile,
+                tag=image_tag,
+                build_context=build_ctx,
+            )
+
+            if returncode != 0:
+                logger.error(
+                    "Failed to build image for manifest instance %s: %s",
+                    instance_name,
+                    stderr,
+                )
+                raise HTTPException(
+                    status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                    detail=f"Failed to build Docker image: {stderr[:500]}",
+                )
+
+            logger.info(
+                "Built manifest image %s for instance %s",
+                image_tag,
+                instance_name,
+            )
+
+            variables = {
+                "IMAGE_TAG": image_tag,
+                "INSTANCE_NAME": instance_name.lower(),
+                "INSTANCE_DIR": instance_dir,
+                "REPO_PATH": repo_path,
+                "SSH_PATH": "",
+                "TOOL_PORT": tool_port,
+                "EXTRA_ENV": {},
+                "EXTRA_VOLUMES": [],
+            }
+            compose_content = compile_compose(manifest, variables)
+            write_compose_file(instance_dir, compose_content)
+
         else:
-            # Render compose template
+            # Render compose template (legacy)
             variables = {
                 "REPO_PATH": repo_path,
                 "INSTANCE_NAME": instance_name,
@@ -976,15 +1116,14 @@ async def _prepare_manifest_instance(
     instance: ToolInstance,
     instance_dir: str,
     repo_path: str,
-    configs: list,
     env_vars: dict,
     extra_volumes: list,
     working_directory: str | None,
-) -> tuple[str, str, dict]:
+) -> tuple[str, str, dict, str]:
     """Build image and generate compose from a manifest-based tool type.
 
     Returns:
-        Tuple of (image_tag, compose_content, resolved_manifest)
+        Tuple of (image_tag, compose_content, resolved_manifest, home_dir)
     """
     from src.models.tool_definition_manifest import ToolDefinitionManifest
 
@@ -1011,22 +1150,7 @@ async def _prepare_manifest_instance(
                 manifest_def.id,
             )
 
-    # Merge tool configs
-    tool_config_dicts = [
-        {
-            "config_type": c.config_type,
-            "key": c.key,
-            "value": c.value,
-            "file_path": c.file_path,
-            "port_override": c.port_override,
-            "start_command": c.start_command,
-            "working_directory": c.working_directory,
-            "environment_variables": c.environment_variables,
-            "volumes": c.volumes,
-        }
-        for c in configs
-    ]
-    manifest = merge_with_config(manifest, tool_config_dicts)
+    manifest = merge_with_config(manifest)
 
     # Resolve extra env and volumes from merge_with_config
     extra_env = manifest.pop("_extra_env", {})
@@ -1050,6 +1174,12 @@ async def _prepare_manifest_instance(
         dockerfile = compile_dockerfile(manifest)
         entrypoint = compile_entrypoint(manifest)
 
+        logger.debug(
+            "Compiled Dockerfile for instance %s (%d chars)",
+            instance.id,
+            len(dockerfile),
+        )
+
         build_ctx = {
             "Dockerfile": dockerfile,
             ".headquarter/entrypoint.sh": entrypoint,
@@ -1104,7 +1234,8 @@ async def _prepare_manifest_instance(
     instance.image_tag = image_tag
     instance.manifest_compiled_at = datetime.now()
 
-    return image_tag, compose_content, manifest
+    home_dir = get_manifest_home_dir(manifest)
+    return image_tag, compose_content, manifest, home_dir
 
 
 @router.post(
@@ -1159,50 +1290,22 @@ async def start_instance(
     await session.commit()
     logger.info("Starting instance %s (name=%s)", instance.id, instance.name)
 
-    # Fetch tool configs for this tool type
+    # Runtime overrides populated by config profiles
     env_vars = {}
     config_files = {}
     port_override = None
     start_command = None
     working_directory = None
-    extra_env_vars = {}
     extra_volumes = []
 
-    config_query = (
-        select(ToolConfig)
-        .where(
-            ToolConfig.user_id == user_id,
-            ToolConfig.tool_type_id == instance.tool_type_id,
-        )
-        .where(
-            (ToolConfig.project_id == project_id) | (ToolConfig.project_id.is_(None))
-        )
-    )
-
-    config_result = await session.execute(config_query)
-    configs = config_result.scalars().all()
-    logger.debug("Found %d tool configs for instance %s", len(configs), instance.id)
-
-    for config in configs:
-        if config.config_type == "env":
-            env_vars[config.key] = config.value
-        elif config.config_type == "file" and config.file_path:
-            config_files[config.file_path] = config.value
-
-        # Handle new config fields
-        if config.port_override:
-            port_override = config.port_override
-        if config.start_command:
-            start_command = config.start_command
-        if config.working_directory:
-            working_directory = config.working_directory
-        if config.environment_variables:
-            extra_env_vars.update(config.environment_variables)
-        if config.volumes:
-            extra_volumes.extend(config.volumes)
-
-    # Merge extra env vars
-    env_vars.update(extra_env_vars)
+    # Fetch tool type early to determine home directory
+    tool_type = await session.get(ToolType, instance.tool_type_id)
+    home_dir = "/root"
+    if tool_type and tool_type.definition_type == "manifest" and tool_type.manifest_id:
+        from src.models.tool_definition_manifest import ToolDefinitionManifest
+        manifest_def = await session.get(ToolDefinitionManifest, tool_type.manifest_id)
+        if manifest_def:
+            home_dir = get_manifest_home_dir(dict(manifest_def.manifest))
 
     # Apply selected config profile if any
     instance_dir = os.path.dirname(instance.compose_path)
@@ -1212,7 +1315,7 @@ async def start_instance(
                 session, instance.selected_config_profile_id
             )
             profile_env, profile_files, profile_mounts, profile_hints = (
-                apply_resolved_profile(instance_dir, resolved)
+                apply_resolved_profile(instance_dir, resolved, home_dir)
             )
             # Profile env vars override tool config env vars
             env_vars.update(profile_env)
@@ -1222,7 +1325,7 @@ async def start_instance(
             extra_volumes.extend(profile_mounts)
             # Git repository mounts are resolved and added
             git_mount_volumes = await _resolve_git_mounts(
-                session, resolved, instance_dir, working_directory
+                session, resolved, instance_dir, working_directory, home_dir
             )
             extra_volumes.extend(git_mount_volumes)
             # Profile runtime hints override tool config values
@@ -1266,7 +1369,6 @@ async def start_instance(
         )
 
     # ── MANIFEST-BASED FLOW ──────────────────────────────────────
-    tool_type = await session.get(ToolType, instance.tool_type_id)
     resolved_manifest = None
 
     if tool_type and tool_type.definition_type == "manifest" and tool_type.manifest_id:
@@ -1283,12 +1385,12 @@ async def start_instance(
                 image_tag,
                 compose_content,
                 resolved_manifest,
+                _home_dir,
             ) = await _prepare_manifest_instance(
                 session=session,
                 instance=instance,
                 instance_dir=instance_dir,
                 repo_path=repo_path,
-                configs=configs,
                 env_vars=env_vars,
                 extra_volumes=extra_volumes,
                 working_directory=working_directory,
@@ -1342,6 +1444,7 @@ async def start_instance(
                 start_command,
                 working_directory,
                 extra_volumes,
+                home_dir,
             )
             logger.debug("Modified compose file for instance %s", instance.id)
 

apps/api/src/api/tool_types.py

@@ -35,6 +35,7 @@ class ToolTypeCreate(BaseModel):
     description: str | None = None
     default_port: int = 0
     definition_type: str = "compose"
+    manifest_id: uuid.UUID | None = None
     compose_template: str | None = None
     dockerfile_template: str | None = None
     build_context: dict | None = None
@@ -48,8 +49,10 @@ class ToolTypeCreate(BaseModel):
     @field_validator("definition_type")
     @classmethod
     def validate_definition_type(cls, v: str) -> str:
-        if v not in ("compose", "dockerfile"):
-            raise ValueError("definition_type must be 'compose' or 'dockerfile'")
+        if v not in ("compose", "dockerfile", "manifest"):
+            raise ValueError(
+                "definition_type must be 'compose', 'dockerfile', or 'manifest'"
+            )
         return v
 
     @field_validator("compose_template")
@@ -58,10 +61,12 @@ class ToolTypeCreate(BaseModel):
         data = info.data
         if data.get("definition_type") != "compose":
             return v
-        
-        if v is None:
-            raise ValueError("compose_template is required when definition_type is 'compose'")
-        
+
+        if v is None or not v.strip():
+            raise ValueError(
+                "compose_template is required when definition_type is 'compose'"
+            )
+
         validate_compose_yaml(v)
         return v
 
@@ -71,13 +76,15 @@ class ToolTypeCreate(BaseModel):
         data = info.data
         if data.get("definition_type") != "dockerfile":
             return v
-        
-        if v is None:
-            raise ValueError("dockerfile_template is required when definition_type is 'dockerfile'")
-        
+
+        if v is None or not v.strip():
+            raise ValueError(
+                "dockerfile_template is required when definition_type is 'dockerfile'"
+            )
+
         if not v.strip().startswith("FROM"):
             raise ValueError("Dockerfile must start with a FROM instruction")
-        
+
         return v
 
     @field_validator("interface_type")
@@ -103,39 +110,62 @@ class ToolTypeCreate(BaseModel):
     def validate_required_variables(cls, v: list[str], info) -> list[str]:
         if not v:
             return v
-        
+
         data = info.data
         if data.get("definition_type") != "compose":
             return v
-        
+
         template = data.get("compose_template")
         if not template:
             return v
-        
+
         for var in v:
             placeholder = f"{{{{{var}}}}}"
             if placeholder not in template:
-                raise ValueError(f"Required variable '{var}' not found in compose template")
-        
+                raise ValueError(
+                    f"Required variable '{var}' not found in compose template"
+                )
+
         return v
 
     @model_validator(mode="after")
     def validate_templates(self) -> "ToolTypeCreate":
-        if self.definition_type == "dockerfile" and self.dockerfile_template is None:
-            raise ValueError("dockerfile_template is required when definition_type is 'dockerfile'")
-        if self.definition_type == "compose" and self.compose_template is None:
-            raise ValueError("compose_template is required when definition_type is 'compose'")
-        
+        if self.definition_type == "manifest":
+            if self.manifest_id is None:
+                raise ValueError(
+                    "manifest_id is required when definition_type is 'manifest'"
+                )
+            return self
+
+        if self.definition_type == "dockerfile" and (
+            self.dockerfile_template is None or not self.dockerfile_template.strip()
+        ):
+            raise ValueError(
+                "dockerfile_template is required when definition_type is 'dockerfile'"
+            )
+        if self.definition_type == "compose" and (
+            self.compose_template is None or not self.compose_template.strip()
+        ):
+            raise ValueError(
+                "compose_template is required when definition_type is 'compose'"
+            )
+
         # Validate that default_port is exposed in compose template (only if requires_port)
-        if self.requires_port and self.definition_type == "compose" and self.compose_template:
+        if (
+            self.requires_port
+            and self.definition_type == "compose"
+            and self.compose_template
+        ):
             try:
                 parsed = validate_compose_yaml(self.compose_template)
             except ValueError:
                 return self
-            
+
             if not check_port_exposed(parsed, self.default_port):
-                raise ValueError(f"Port {self.default_port} is not exposed in the compose template. Add it to the 'ports' section.")
-        
+                raise ValueError(
+                    f"Port {self.default_port} is not exposed in the compose template. Add it to the 'ports' section."
+                )
+
         return self
 
 
@@ -144,6 +174,7 @@ class ToolTypeUpdate(BaseModel):
     description: str | None = None
     default_port: int | None = None
     definition_type: str | None = None
+    manifest_id: uuid.UUID | None = None
     compose_template: str | None = None
     dockerfile_template: str | None = None
     build_context: dict | None = None
@@ -159,8 +190,10 @@ class ToolTypeUpdate(BaseModel):
     def validate_definition_type(cls, v: str | None) -> str | None:
         if v is None:
             return v
-        if v not in ("compose", "dockerfile"):
-            raise ValueError("definition_type must be 'compose' or 'dockerfile'")
+        if v not in ("compose", "dockerfile", "manifest"):
+            raise ValueError(
+                "definition_type must be 'compose', 'dockerfile', or 'manifest'"
+            )
         return v
 
     @field_validator("interface_type")
@@ -191,15 +224,15 @@ class ToolTypeUpdate(BaseModel):
     def validate_dockerfile_template(cls, v: str | None, info) -> str | None:
         if v is None:
             return v
-        
+
         data = info.data
         definition_type = data.get("definition_type")
         if definition_type and definition_type != "dockerfile":
             return v
-        
+
         if not v.strip().startswith("FROM"):
             raise ValueError("Dockerfile must start with a FROM instruction")
-        
+
         return v
 
 
@@ -215,6 +248,7 @@ class ToolTypeResponse(BaseModel):
     requires_port: bool
     default_port: int
     definition_type: str
+    manifest_id: uuid.UUID | None
     compose_template: str | None
     dockerfile_template: str | None
     build_context: dict | None
@@ -250,18 +284,22 @@ async def create_tool_type(
     """
     user = await _get_user(session, user_id)
     await _require_admin(user)
-    
+
     # Check for duplicate name
     existing = await session.scalar(select(ToolType).where(ToolType.name == data.name))
     if existing:
-        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="tool type with this name already exists")
-    
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail="tool type with this name already exists",
+        )
+
     tool_type = ToolType(
         name=data.name,
         display_name=data.display_name,
         description=data.description,
         default_port=data.default_port,
         definition_type=data.definition_type,
+        manifest_id=data.manifest_id,
         compose_template=data.compose_template,
         dockerfile_template=data.dockerfile_template,
         build_context=data.build_context,
@@ -327,7 +365,9 @@ async def get_tool_type(
     await _get_user(session, user_id)
     tool_type = await session.get(ToolType, tool_type_id)
     if tool_type is None:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="tool type not found")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="tool type not found"
+        )
     return tool_type
 
 
@@ -356,15 +396,17 @@ async def update_tool_type(
     """
     user = await _get_user(session, user_id)
     await _require_admin(user)
-    
+
     tool_type = await session.get(ToolType, tool_type_id)
     if tool_type is None:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="tool type not found")
-    
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="tool type not found"
+        )
+
     # Built-in tool types can now be modified
-    
+
     update_data = data.model_dump(exclude_unset=True)
-    
+
     # Validate port if being updated
     requires_port = update_data.get("requires_port", tool_type.requires_port)
     if "default_port" in update_data and requires_port:
@@ -372,9 +414,9 @@ async def update_tool_type(
         if new_port <= 0 or new_port > 65535:
             raise HTTPException(
                 status_code=status.HTTP_400_BAD_REQUEST,
-                detail="Port must be between 1 and 65535"
+                detail="Port must be between 1 and 65535",
             )
-        
+
         # Only validate port exposure for compose definitions
         definition_type = update_data.get("definition_type", tool_type.definition_type)
         if definition_type == "compose":
@@ -385,12 +427,11 @@ async def update_tool_type(
                     if not check_port_exposed(parsed, new_port):
                         raise HTTPException(
                             status_code=status.HTTP_400_BAD_REQUEST,
-                            detail=f"Port {new_port} is not exposed in the compose template"
+                            detail=f"Port {new_port} is not exposed in the compose template",
                         )
                 except ValueError as e:
                     raise HTTPException(
-                        status_code=status.HTTP_400_BAD_REQUEST,
-                        detail=str(e)
+                        status_code=status.HTTP_400_BAD_REQUEST, detail=str(e)
                     )
 
     # Validate required variables for compose definitions
@@ -404,10 +445,17 @@ async def update_tool_type(
             template = tool_type.compose_template
             if template:
                 validate_required_variables(template, update_data["required_variables"])
-    
+
+    # When switching to manifest, clear legacy templates
+    if definition_type == "manifest":
+        if "manifest_id" in update_data:
+            tool_type.manifest_id = update_data["manifest_id"]
+        tool_type.compose_template = None
+        tool_type.dockerfile_template = None
+
     for field, value in update_data.items():
         setattr(tool_type, field, value)
-    
+
     await session.commit()
     await session.refresh(tool_type)
     return tool_type
@@ -458,8 +506,11 @@ async def validate_tool_type_template(
         elif not data.dockerfile_template.strip().startswith("FROM"):
             errors.append("Dockerfile must start with a FROM instruction")
 
+    elif data.definition_type == "manifest":
+        pass  # Manifest validation is handled separately
+
     else:
-        errors.append("definition_type must be 'compose' or 'dockerfile'")
+        errors.append("definition_type must be 'compose', 'dockerfile', or 'manifest'")
 
     return {
         "valid": len(errors) == 0,
@@ -490,10 +541,12 @@ async def validate_tool_type(
     await _get_user(session, user_id)
     tool_type = await session.get(ToolType, tool_type_id)
     if tool_type is None:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="tool type not found")
-    
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="tool type not found"
+        )
+
     errors = []
-    
+
     if tool_type.definition_type == "compose":
         if not tool_type.compose_template:
             errors.append("Compose template is empty")
@@ -502,13 +555,17 @@ async def validate_tool_type(
                 validate_compose_yaml(tool_type.compose_template)
             except ValueError as e:
                 errors.append(str(e))
-    
+
     elif tool_type.definition_type == "dockerfile":
         if not tool_type.dockerfile_template:
             errors.append("Dockerfile template is empty")
         elif not tool_type.dockerfile_template.strip().startswith("FROM"):
             errors.append("Dockerfile must start with a FROM instruction")
-    
+
+    elif tool_type.definition_type == "manifest":
+        if not tool_type.manifest_id:
+            errors.append("Manifest reference is missing")
+
     return {
         "valid": len(errors) == 0,
         "errors": errors,
@@ -538,12 +595,14 @@ async def delete_tool_type(
     """
     user = await _get_user(session, user_id)
     await _require_admin(user)
-    
+
     tool_type = await session.get(ToolType, tool_type_id)
     if tool_type is None:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="tool type not found")
-    
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="tool type not found"
+        )
+
     # Built-in tool types can now be deleted
-    
+
     await session.delete(tool_type)
     await session.commit()

apps/api/src/main.py

@@ -15,9 +15,7 @@ from src.api.projects import router as projects_router
 from src.api.ssh_keys import router as ssh_keys_router
 from src.api.terminal import router as terminal_router
 from src.api.instance_proxy import router as instance_proxy_router
-from src.api.config_folders import router as config_folders_router
 from src.api.config_profiles import router as config_profiles_router
-from src.api.tool_configs import router as tool_configs_router
 from src.api.tool_definitions import router as tool_definitions_router
 from src.api.tool_instances import router as tool_instances_router
 from src.api.tool_instances import sessions_router
@@ -25,6 +23,7 @@ from src.api.tool_types import router as tool_types_router
 from src.api.user_config import router as user_config_router
 from src.api.users import router as users_router
 from src.config import Settings
+from src.models.terminal_session import TerminalSessionModel  # noqa: F401 – Alembic model discovery
 from src.database import init_database
 from src.logging_config import (
     ExceptionLoggingMiddleware,
@@ -129,10 +128,8 @@ app.include_router(git_repositories_router)
 app.include_router(user_config_router)
 app.include_router(tool_types_router)
 app.include_router(tool_definitions_router)
-app.include_router(config_folders_router)
 app.include_router(config_profiles_router)
 app.include_router(tool_instances_router)
-app.include_router(tool_configs_router)
 app.include_router(sessions_router)
 app.include_router(instance_proxy_router)
 app.include_router(terminal_router)

apps/api/src/models/__init__.py

@@ -1,9 +1,9 @@
 from src.models.base import Base
-from src.models.config_folder import ConfigFolder
 from src.models.config_profile import ConfigProfile, ConfigProfileInclude
 from src.models.git_repository import GitRepository
 from src.models.project import Project
 from src.models.ssh_key import SSHKey
+from src.models.terminal_session import TerminalSessionModel
 from src.models.tool_definition_manifest import ToolDefinitionManifest
 from src.models.tool_instance import ToolInstance
 from src.models.tool_type import ToolType
@@ -12,12 +12,12 @@ from src.models.user_config import UserConfig
 
 __all__ = [
     "Base",
-    "ConfigFolder",
     "ConfigProfile",
     "ConfigProfileInclude",
     "GitRepository",
     "Project",
     "SSHKey",
+    "TerminalSessionModel",
     "ToolDefinitionManifest",
     "ToolInstance",
     "ToolType",

apps/api/src/models/config_folder.py

@@ -1,31 +0,0 @@
-import uuid
-from typing import TYPE_CHECKING
-
-from sqlalchemy import Boolean, ForeignKey, JSON, String, Text
-from sqlalchemy import Uuid as UUID
-from sqlalchemy.orm import Mapped, mapped_column, relationship
-
-from src.models.base import Base, TimestampMixin, UUIDPrimaryKeyMixin
-
-if TYPE_CHECKING:
-    from src.models.user import User
-
-
-class ConfigFolder(UUIDPrimaryKeyMixin, TimestampMixin, Base):
-    __tablename__ = "config_folders"
-
-    user_id: Mapped[uuid.UUID] = mapped_column(
-        UUID(), ForeignKey("users.id", ondelete="CASCADE"), nullable=False
-    )
-    name: Mapped[str] = mapped_column(String(255), nullable=False)
-    description: Mapped[str | None] = mapped_column(Text, nullable=True)
-    mount_path: Mapped[str] = mapped_column(String(1024), nullable=False)
-    files: Mapped[dict] = mapped_column(
-        JSON, default=dict, nullable=False
-    )  # {"relative/path": "content", ...}
-    project_overrides: Mapped[dict | None] = mapped_column(
-        JSON, default=dict, nullable=True
-    )  # {"project_id": {"mount_path": "...", "files": {...}}}
-    is_active: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
-
-    user: Mapped["User"] = relationship()

apps/api/src/models/terminal_session.py

@@ -0,0 +1,37 @@
+"""Terminal session database model."""
+
+import uuid
+from datetime import datetime
+
+from sqlalchemy import DateTime, ForeignKey, String
+from sqlalchemy import Uuid as UUID
+from sqlalchemy.orm import Mapped, mapped_column
+
+from src.models.base import Base, TimestampMixin, UUIDPrimaryKeyMixin
+
+
+class TerminalSessionModel(UUIDPrimaryKeyMixin, TimestampMixin, Base):
+    """Database model for terminal session metadata."""
+
+    __tablename__ = "terminal_sessions"
+
+    instance_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(),
+        ForeignKey("tool_instances.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+    name: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    status: Mapped[str] = mapped_column(
+        String(50),
+        nullable=False,
+        default="active",
+    )
+    last_activity_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True),
+        nullable=True,
+    )
+    closed_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True),
+        nullable=True,
+    )

apps/api/src/models/tool_config.py

@@ -1,48 +0,0 @@
-import uuid
-from typing import TYPE_CHECKING
-
-from sqlalchemy import ForeignKey, JSON, String, Text
-from sqlalchemy import Uuid as UUID
-from sqlalchemy.orm import Mapped, mapped_column, relationship
-
-from src.models.base import Base, TimestampMixin, UUIDPrimaryKeyMixin
-
-if TYPE_CHECKING:
-    from src.models.project import Project
-    from src.models.tool_type import ToolType
-    from src.models.user import User
-
-
-class ToolConfig(UUIDPrimaryKeyMixin, TimestampMixin, Base):
-    __tablename__ = "tool_configs"
-
-    user_id: Mapped[uuid.UUID] = mapped_column(
-        UUID(), ForeignKey("users.id"), nullable=False
-    )
-    tool_type_id: Mapped[uuid.UUID] = mapped_column(
-        UUID(), ForeignKey("tool_types.id"), nullable=False
-    )
-    project_id: Mapped[uuid.UUID | None] = mapped_column(
-        UUID(), ForeignKey("projects.id"), nullable=True
-    )
-    key: Mapped[str] = mapped_column(String(255), nullable=False)
-    value: Mapped[str] = mapped_column(Text, nullable=False)
-    config_type: Mapped[str] = mapped_column(
-        String(20), nullable=False, default="env"
-    )  # "env" or "file"
-    file_path: Mapped[str | None] = mapped_column(
-        String(1024), nullable=True
-    )  # Only for file type
-    port_override: Mapped[int | None] = mapped_column(nullable=True)
-    start_command: Mapped[str | None] = mapped_column(Text, nullable=True)
-    working_directory: Mapped[str | None] = mapped_column(Text, nullable=True)
-    environment_variables: Mapped[dict | None] = mapped_column(
-        JSON, default=dict, nullable=True
-    )
-    volumes: Mapped[list[dict] | None] = mapped_column(
-        JSON, default=list, nullable=True
-    )
-
-    user: Mapped["User"] = relationship()
-    tool_type: Mapped["ToolType"] = relationship()
-    project: Mapped["Project | None"] = relationship()

apps/api/src/services/config_profile_resolver.py

@@ -5,6 +5,7 @@ and cycle protection.
 """
 
 import logging
+import os
 import uuid
 from dataclasses import dataclass, field
 from typing import Any
@@ -57,7 +58,9 @@ class ResolvedProfile:
     included_profiles: list[dict[str, Any]] = field(default_factory=list)
 
 
-def _detect_cycle(profile_id: uuid.UUID, visited: set[uuid.UUID], path: list[uuid.UUID]) -> bool:
+def _detect_cycle(
+    profile_id: uuid.UUID, visited: set[uuid.UUID], path: list[uuid.UUID]
+) -> bool:
     """Detect if adding profile_id to path would create a cycle.
 
     Args:
@@ -176,21 +179,59 @@ def _merge_git_mounts(
 ) -> list[dict[str, Any]]:
     """Merge git mounts from included profiles.
 
-    Later mounts override earlier ones with the same remote_url + target_path combo.
+    Entries with the same remote_url + branch have their mappings concatenated.
+    Different repos are kept as separate entries.
+    All entries are normalized to the mappings format.
     """
     result = list(base)
-    # Build lookup by (remote_url, target_path)
-    seen = {(m["remote_url"], m["target_path"]): i for i, m in enumerate(result)}
+    # Normalize existing entries to mappings format
+    for i, m in enumerate(result):
+        result[i] = _normalize_git_mount_entry(dict(m))
+
+    # Build lookup by (remote_url, branch)
+    seen = {}
+    for i, m in enumerate(result):
+        key = (m["remote_url"], m.get("branch"))
+        seen[key] = i
+
     for mount in overlay:
-        key = (mount["remote_url"], mount["target_path"])
+        mount = _normalize_git_mount_entry(dict(mount))
+        key = (mount["remote_url"], mount.get("branch"))
         if key in seen:
-            result[seen[key]] = dict(mount)
+            # Same repo+branch: concatenate mappings, dedup by (source_path, target_path)
+            existing = result[seen[key]]
+            existing_sources = {
+                (m["source_path"], m["target_path"])
+                for m in existing.get("mappings", [])
+            }
+            for mapping in mount.get("mappings", []):
+                map_key = (mapping["source_path"], mapping["target_path"])
+                if map_key not in existing_sources:
+                    existing["mappings"].append(dict(mapping))
+                    existing_sources.add(map_key)
         else:
             seen[key] = len(result)
-            result.append(dict(mount))
+            result.append(mount)
     return result
 
 
+def _normalize_git_mount_entry(entry: dict[str, Any]) -> dict[str, Any]:
+    """Normalize a git mount entry to the unified mappings format.
+
+    Converts legacy source_path + target_path into a single-entry mappings array.
+    """
+    entry = dict(entry)
+    if "mappings" not in entry or not entry.get("mappings"):
+        source = entry.get("source_path", ".")
+        target = entry.get("target_path")
+        if target is not None:
+            entry["mappings"] = [{"source_path": source, "target_path": target}]
+    # Remove legacy fields once normalized
+    entry.pop("source_path", None)
+    entry.pop("target_path", None)
+    return entry
+
+
 async def _resolve_profile_recursive(
     session: AsyncSession,
     profile_id: uuid.UUID,
@@ -214,7 +255,9 @@ async def _resolve_profile_recursive(
     """
     if _detect_cycle(profile_id, visited, path):
         cycle_path = " -> ".join(str(p) for p in path + [profile_id])
-        raise ConfigProfileCycleError(f"Cycle detected in profile includes: {cycle_path}")
+        raise ConfigProfileCycleError(
+            f"Cycle detected in profile includes: {cycle_path}"
+        )
 
     profile = await session.get(ConfigProfile, profile_id)
     if profile is None:
@@ -241,13 +284,18 @@ async def _resolve_profile_recursive(
         included = await _resolve_profile_recursive(
             session, include.included_profile_id, new_visited, new_path
         )
-        result.included_profiles.append({
-            "id": str(included.profile_id),
-            "name": included.profile_name,
-        })
+        result.included_profiles.append(
+            {
+                "id": str(included.profile_id),
+                "name": included.profile_name,
+            }
+        )
 
         result.env_vars = _merge_env_vars(
-            result.env_vars, included.env_vars, result.env_overrides, included.profile_name
+            result.env_vars,
+            included.env_vars,
+            result.env_overrides,
+            included.profile_name,
         )
         result.runtime_hints = _merge_runtime_hints(
             result.runtime_hints,
@@ -391,6 +439,7 @@ async def check_include_cycle(
 def apply_resolved_profile(
     instance_dir: str,
     resolved: ResolvedProfile,
+    home_dir: str = "/root",
 ) -> tuple[dict[str, str], dict[str, str], list[dict], dict[str, Any]]:
     """Apply a resolved profile to an instance directory.
 
@@ -420,14 +469,19 @@ def apply_resolved_profile(
         try:
             full_path.resolve().relative_to(instance_path.resolve())
         except ValueError:
-            logger.warning("Profile file path escapes instance directory: %s", file_path)
+            logger.warning(
+                "Profile file path escapes instance directory: %s", file_path
+            )
             continue
         full_path.parent.mkdir(parents=True, exist_ok=True)
         full_path.write_text(content)
 
     # Stage mount files and prepare volume mounts
     for mount in resolved.mounts.values():
-        mount_dir = instance_path / "mounts" / mount.target.lstrip("/").replace("/", "_")
+        expanded_target = expand_container_path(mount.target, home_dir)
+        mount_dir = (
+            instance_path / "mounts" / expanded_target.lstrip("/").replace("/", "_")
+        )
         mount_dir.mkdir(parents=True, exist_ok=True)
 
         for file_path, content in mount.files.items():
@@ -440,15 +494,41 @@ def apply_resolved_profile(
             full_path.parent.mkdir(parents=True, exist_ok=True)
             full_path.write_text(content)
 
-        volume_mounts.append({
-            "source": str(mount_dir),
-            "target": mount.target,
-            "type": "bind",
-        })
+        volume_mounts.append(
+            {
+                "source": str(mount_dir),
+                "target": expanded_target,
+                "type": "bind",
+            }
+        )
 
     return env_vars, files, volume_mounts, resolved.runtime_hints
 
 
+def expand_container_path(path: str, home_dir: str) -> str:
+    """Expand ~ and $HOME in a container path to the actual home directory.
+
+    Only expands at the start of the path (e.g., ~/foo, $HOME/foo, $HOME).
+    Leaves mid-string occurrences unchanged.
+
+    Args:
+        path: Container path that may contain ~ or $HOME.
+        home_dir: The container's home directory (e.g., /home/user or /root).
+
+    Returns:
+        Path with ~ and $HOME expanded.
+    """
+    if path.startswith("~/"):
+        return os.path.join(home_dir, path[2:])
+    if path == "~":
+        return home_dir
+    if path.startswith("$HOME/"):
+        return home_dir + "/" + path[6:]
+    if path == "$HOME":
+        return home_dir
+    return path
+
+
 def resolved_profile_to_dict(resolved: ResolvedProfile) -> dict[str, Any]:
     """Convert a ResolvedProfile to a plain dict for serialization.
 

apps/api/src/services/docker_build.py

@@ -6,7 +6,9 @@ import subprocess
 logger = logging.getLogger(__name__)
 
 
-def build_image(instance_dir: str, dockerfile: str, tag: str, build_context: dict | None = None) -> tuple[int, str, str]:
+def build_image(
+    instance_dir: str, dockerfile: str, tag: str, build_context: dict | None = None
+) -> tuple[int, str, str]:
     """Build a Docker image from a Dockerfile.
 
     Args:
@@ -20,10 +22,16 @@ def build_image(instance_dir: str, dockerfile: str, tag: str, build_context: dic
     """
     from pathlib import Path
 
+    # Defensive: normalise any CRLF that may have crept in from manifest DB
+    # strings — Docker's legacy builder treats \r as a character after the
+    # backslash, breaking RUN continuations and producing
+    # "unknown instruction" errors.
+    dockerfile = dockerfile.replace("\r\n", "\n").replace("\r", "\n")
+
     # Write Dockerfile
     dockerfile_path = Path(instance_dir) / "Dockerfile"
-    dockerfile_path.write_text(dockerfile)
-    logger.debug("Wrote Dockerfile to %s", dockerfile_path)
+    dockerfile_path.write_text(dockerfile, newline="\n")
+    logger.debug("Wrote Dockerfile to %s (%d bytes)", dockerfile_path, len(dockerfile))
 
     # Write build context files
     if build_context:
@@ -33,19 +41,27 @@ def build_image(instance_dir: str, dockerfile: str, tag: str, build_context: dic
             try:
                 full_path.resolve().relative_to(Path(instance_dir).resolve())
             except ValueError:
-                logger.error("Build context file path escapes instance directory: %s", file_path)
-                raise ValueError(f"Build context file path '{file_path}' escapes instance directory")
-            
+                logger.error(
+                    "Build context file path escapes instance directory: %s", file_path
+                )
+                raise ValueError(
+                    f"Build context file path '{file_path}' escapes instance directory"
+                )
+
             full_path.parent.mkdir(parents=True, exist_ok=True)
-            full_path.write_text(content)
+            normalized = content.replace("\r\n", "\n").replace("\r", "\n")
+            full_path.write_text(normalized, newline="\n")
             logger.debug("Wrote build context file: %s", full_path)
 
     # Build image
     logger.debug("Building Docker image with tag: %s", tag)
     cmd = [
-        "docker", "build",
-        "-t", tag,
-        "-f", str(dockerfile_path),
+        "docker",
+        "build",
+        "-t",
+        tag,
+        "-f",
+        str(dockerfile_path),
         instance_dir,
     ]
 

apps/api/src/services/manifest_compiler.py

@@ -117,10 +117,10 @@ def compile_dockerfile(manifest: dict) -> str:
     # System packages (apt)
     apt_packages = manifest.get("packages", {}).get("apt", [])
     if apt_packages:
-        lines.append("RUN apt-get update && apt-get install -y \\\\")
+        lines.append("RUN apt-get update && apt-get install -y \\")
         for pkg in apt_packages[:-1]:
-            lines.append(f"    {pkg} \\\\")
-        lines.append(f"    {apt_packages[-1]} \\\\")
+            lines.append(f"    {pkg} \\")
+        lines.append(f"    {apt_packages[-1]} \\")
         lines.append("    && rm -rf /var/lib/apt/lists/*")
         lines.append("")
 
@@ -129,9 +129,9 @@ def compile_dockerfile(manifest: dict) -> str:
     if node:
         version = node.get("version", "20")
         lines.append(
-            f"RUN curl -fsSL https://deb.nodesource.com/setup_{version}.x | bash - && \\\\"
+            f"RUN curl -fsSL https://deb.nodesource.com/setup_{version}.x | bash - && \\"
         )
-        lines.append("    apt-get install -y nodejs && \\\\")
+        lines.append("    apt-get install -y nodejs && \\")
         lines.append("    rm -rf /var/lib/apt/lists/*")
         lines.append("")
 
@@ -157,9 +157,14 @@ def compile_dockerfile(manifest: dict) -> str:
         gid = user["gid"]
         create_home = "-m " if user.get("create_home", True) else ""
         shell = user.get("shell", "/bin/bash")
-        lines.append(f"RUN groupadd -g {gid} {name} && \\\\")
+        lines.append(f"RUN groupadd -g {gid} {name} && \\")
         lines.append(f"    useradd -u {uid} -g {gid} {create_home}-s {shell} {name}")
         lines.append("")
+        # Set HOME and USER for runtime compatibility
+        home = f"/home/{name}"
+        lines.append(f"ENV HOME={home}")
+        lines.append(f"ENV USER={name}")
+        lines.append("")
 
     # Build scripts
     build_scripts = manifest.get("scripts", {}).get("build", [])
@@ -333,6 +338,21 @@ def resolve_mount_source(mount: dict, variables: dict[str, Any]) -> str:
     return ""
 
 
+def get_manifest_home_dir(manifest: dict) -> str:
+    """Get the home directory for a container based on manifest user config.
+
+    Args:
+        manifest: Fully resolved manifest JSON.
+
+    Returns:
+        Home directory path (e.g., /home/user or /root).
+    """
+    user = manifest.get("user")
+    if user and user.get("name"):
+        return f"/home/{user['name']}"
+    return "/root"
+
+
 def compute_image_tag(tool_name: str, manifest: dict) -> str:
     """Compute a deterministic image tag from manifest content.
 
@@ -350,14 +370,11 @@ def compute_image_tag(tool_name: str, manifest: dict) -> str:
     return f"headquarter/{safe_name}-{hash_suffix}:latest"
 
 
-def merge_with_config(
-    manifest: dict, tool_configs: list[dict], profile: dict | None = None
-) -> dict:
-    """Merge ToolConfig and ConfigProfile overrides into a manifest.
+def merge_with_config(manifest: dict, profile: dict | None = None) -> dict:
+    """Merge ConfigProfile overrides into a manifest.
 
     Args:
         manifest: Base manifest from tool definition.
-        tool_configs: List of ToolConfig records.
         profile: Resolved ConfigProfile (optional).
 
     Returns:
@@ -365,29 +382,9 @@ def merge_with_config(
     """
     result = deepcopy(manifest)
 
-    # Apply ToolConfigs
     extra_env: dict[str, str] = {}
     extra_volumes: list[dict] = []
 
-    for config in tool_configs:
-        if config.get("config_type") == "env":
-            extra_env[config["key"]] = config["value"]
-        elif config.get("config_type") == "file" and config.get("file_path"):
-            # Files are handled outside the manifest (written to instance dir)
-            pass
-        if config.get("port_override"):
-            result["default_port"] = config["port_override"]
-        if config.get("start_command"):
-            result["runtime"] = result.get("runtime", {})
-            result["runtime"]["command"] = config["start_command"].split()
-        if config.get("working_directory"):
-            result["runtime"] = result.get("runtime", {})
-            result["runtime"]["working_dir"] = config["working_directory"]
-        if config.get("environment_variables"):
-            extra_env.update(config["environment_variables"])
-        if config.get("volumes"):
-            extra_volumes.extend(config["volumes"])
-
     # Apply ConfigProfile
     if profile:
         if profile.get("environment_variables"):

apps/api/src/services/terminal_manager.py

@@ -3,20 +3,37 @@
 import asyncio
 import logging
 import uuid
+from datetime import datetime, timezone
 
 from fastapi import WebSocket
 
+from src.database import SessionLocal
+from src.models.terminal_session import TerminalSessionModel
 from src.services.terminal_session import TerminalSession
 
 logger = logging.getLogger(__name__)
 
 
+class MaxSessionsExceededError(Exception):
+    """Raised when the maximum number of terminal sessions per instance is reached."""
+
+    def __init__(self, instance_id: str, max_sessions: int = 5) -> None:
+        self.instance_id = instance_id
+        self.max_sessions = max_sessions
+        super().__init__(
+            f"Maximum of {max_sessions} terminal sessions reached for instance {instance_id}"
+        )
+
+
 class TerminalManager:
     """Manages active terminal sessions with persistence support."""
 
+    # Maximum sessions per tool instance
+    MAX_SESSIONS_PER_INSTANCE = 5
+
     def __init__(self) -> None:
-        # Track sessions by instance_id for persistence
-        self._sessions: dict[str, TerminalSession] = {}
+        # Track sessions by (instance_id, session_id) for multi-session support
+        self._sessions: dict[tuple[str, str], TerminalSession] = {}
         self._idle_check_task: asyncio.Task | None = None
         self._start_idle_check()
 
@@ -42,16 +59,133 @@ class TerminalManager:
 
     async def _cleanup_idle_sessions(self) -> None:
         """Clean up sessions that have been idle for too long."""
-        idle_sessions = []
-        for instance_id, session in list(self._sessions.items()):
+        idle_keys = []
+        for (instance_id, session_id), session in list(self._sessions.items()):
             if session.is_idle():
-                idle_sessions.append(instance_id)
-        
-        for instance_id in idle_sessions:
-            logger.info("Cleaning up idle terminal session for instance %s", instance_id)
-            session = self._sessions.pop(instance_id, None)
+                idle_keys.append((instance_id, session_id))
+
+        for key in idle_keys:
+            instance_id, session_id = key
+            logger.info(
+                "Cleaning up idle terminal session %s for instance %s",
+                session_id,
+                instance_id,
+            )
+            session = self._sessions.pop(key, None)
             if session:
                 await session.close()
+                # Update DB status fire-and-forget
+                asyncio.create_task(self._mark_closed_in_db(session_id))
+
+    async def _insert_db_session_row(
+        self,
+        session_id: str,
+        instance_id: uuid.UUID,
+        name: str,
+    ) -> None:
+        """Insert a TerminalSessionModel row into the database."""
+        try:
+            async with SessionLocal() as db_session:
+                db_row = TerminalSessionModel(
+                    id=uuid.UUID(session_id),
+                    instance_id=instance_id,
+                    name=name,
+                    status="active",
+                    created_at=datetime.now(timezone.utc),
+                    last_activity_at=datetime.now(timezone.utc),
+                )
+                db_session.add(db_row)
+                await db_session.commit()
+                logger.debug(
+                    "Inserted terminal session row %s for instance %s",
+                    session_id,
+                    instance_id,
+                )
+        except Exception as exc:
+            logger.error("Failed to insert terminal session row: %s", exc)
+
+    async def _mark_closed_in_db(self, session_id: str) -> None:
+        """Mark a terminal session as closed in the database."""
+        try:
+            async with SessionLocal() as db_session:
+                db_row = await db_session.get(
+                    TerminalSessionModel, uuid.UUID(session_id)
+                )
+                if db_row:
+                    db_row.status = "closed"
+                    db_row.closed_at = datetime.now(timezone.utc)
+                    await db_session.commit()
+                    logger.debug(
+                        "Marked terminal session %s as closed in DB", session_id
+                    )
+        except Exception as exc:
+            logger.error("Failed to mark terminal session as closed in DB: %s", exc)
+
+    def _count_sessions_for_instance(self, instance_id_str: str) -> int:
+        """Count active in-memory sessions for a given instance."""
+        return sum(1 for (iid, _sid) in self._sessions if iid == instance_id_str)
+
+    async def create_session(
+        self,
+        instance_id: uuid.UUID,
+        container_id: str,
+        startup_command: str | None = None,
+        name: str | None = None,
+        session_id: str | None = None,
+    ) -> TerminalSession:
+        """Create a new terminal session for an instance.
+
+        Enforces a maximum of MAX_SESSIONS_PER_INSTANCE sessions per instance.
+        Inserts a DB row fire-and-forget.
+
+        Args:
+            instance_id: UUID of the tool instance.
+            container_id: Docker container ID.
+            startup_command: Optional startup command to run.
+            name: Optional session name (auto-generated if omitted).
+
+        Returns:
+            The newly created TerminalSession.
+
+        Raises:
+            MaxSessionsExceededError: If the instance already has max sessions.
+        """
+        instance_id_str = str(instance_id)
+
+        if (
+            self._count_sessions_for_instance(instance_id_str)
+            >= self.MAX_SESSIONS_PER_INSTANCE
+        ):
+            raise MaxSessionsExceededError(
+                instance_id_str, self.MAX_SESSIONS_PER_INSTANCE
+            )
+
+        if session_id is None:
+            session_id = str(uuid.uuid4())
+        session = TerminalSession(
+            session_id=session_id,
+            instance_id=instance_id,
+            container_id=container_id,
+            startup_command=startup_command,
+            name=name,
+        )
+        await session.start(startup_command=startup_command)
+
+        key = (instance_id_str, session_id)
+        self._sessions[key] = session
+
+        # Fire-and-forget DB insert (skip if row already exists)
+        asyncio.create_task(
+            self._insert_db_session_row(session_id, instance_id, session.name)
+        )
+
+        logger.info(
+            "Created terminal session %s for instance %s (name=%s)",
+            session_id,
+            instance_id,
+            session.name,
+        )
+        return session
 
     async def get_or_create_session(
         self,
@@ -59,61 +193,146 @@ class TerminalManager:
         container_id: str,
         startup_command: str | None = None,
     ) -> TerminalSession:
-        """Get existing session or create a new one."""
+        """Get existing session or create a new one.
+
+        Backward-compatible alias that uses 'default' as the session_id.
+        """
         # Ensure idle check is running (lazy start)
         self._start_idle_check()
-        
+
         instance_id_str = str(instance_id)
-        
-        # Check for existing session
-        if instance_id_str in self._sessions:
-            session = self._sessions[instance_id_str]
-            
+        key = (instance_id_str, "default")
+
+        # Check for existing default session
+        if key in self._sessions:
+            session = self._sessions[key]
+
             # Check if session is still alive
             if session.is_alive():
-                logger.debug("Reattaching to existing terminal session for instance %s", instance_id)
+                logger.debug(
+                    "Reattaching to existing terminal session for instance %s",
+                    instance_id,
+                )
                 return session
             else:
                 # Session died, clean it up
-                logger.debug("Existing session for instance %s is dead, cleaning up", instance_id)
+                logger.debug(
+                    "Existing session for instance %s is dead, cleaning up",
+                    instance_id,
+                )
                 await session.close()
-                del self._sessions[instance_id_str]
-        
-        # Create new session
-        logger.info("Creating new terminal session for instance %s", instance_id)
+                del self._sessions[key]
+
+        # Create new default session
+        logger.info(
+            "Creating new default terminal session for instance %s", instance_id
+        )
         session_id = str(uuid.uuid4())
-        session = TerminalSession(session_id, instance_id, container_id, startup_command=startup_command)
+        session = TerminalSession(
+            session_id=session_id,
+            instance_id=instance_id,
+            container_id=container_id,
+            startup_command=startup_command,
+            name="Session 1",
+        )
         await session.start(startup_command=startup_command)
-        self._sessions[instance_id_str] = session
-        
+        self._sessions[key] = session
+
+        # Fire-and-forget DB insert
+        asyncio.create_task(
+            self._insert_db_session_row(session_id, instance_id, session.name)
+        )
+
         return session
 
+    def get_session(
+        self,
+        instance_id: str,
+        session_id: str,
+    ) -> TerminalSession | None:
+        """Lookup a session by composite key, or by internal session_id."""
+        session = self._sessions.get((instance_id, session_id))
+        if session is not None:
+            return session
+        # Fallback: search by internal TerminalSession.session_id
+        for (iid, _sid), sess in self._sessions.items():
+            if iid == instance_id and sess.session_id == session_id:
+                return sess
+        return None
+
+    def _find_key_by_internal_id(
+        self,
+        instance_id: str,
+        internal_session_id: str,
+    ) -> tuple[str, str] | None:
+        """Find the manager dict key for a session by its internal session_id."""
+        for (iid, sid), session in self._sessions.items():
+            if iid == instance_id and session.session_id == internal_session_id:
+                return (iid, sid)
+        return None
+
+    def get_sessions_for_instance(
+        self,
+        instance_id: str,
+    ) -> list[TerminalSession]:
+        """Return all in-memory sessions for a given instance."""
+        return [
+            session
+            for (iid, _sid), session in self._sessions.items()
+            if iid == instance_id
+        ]
+
+    async def close_session(
+        self,
+        instance_id: str,
+        session_id: str,
+    ) -> None:
+        """Close a specific session and update its DB status."""
+        key = (instance_id, session_id)
+        session = self._sessions.pop(key, None)
+        if session:
+            await session.close()
+            # Fire-and-forget DB update
+            asyncio.create_task(self._mark_closed_in_db(session_id))
+            logger.info(
+                "Closed terminal session %s for instance %s",
+                session_id,
+                instance_id,
+            )
+
     async def attach_websocket(
         self,
         session: TerminalSession,
         websocket: WebSocket,
     ) -> None:
-        """Attach a WebSocket to an existing session."""
-        # Handle concurrent connections - close existing ones
+        """Attach a WebSocket to an existing session.
+
+        Closes existing WebSocket connections only for this specific session.
+        """
+        # Handle concurrent connections - close existing ones within the same session
         if session.has_websockets():
-            logger.debug("Closing existing WebSocket connections for instance %s", session.instance_id)
+            logger.debug(
+                "Closing existing WebSocket connections for session %s (instance %s)",
+                session.session_id,
+                session.instance_id,
+            )
             for ws in list(session._websockets):
                 try:
                     await ws.close(code=4000, reason="New connection established")
                 except Exception:
-                    pass
+                    pass  # noqa: S110
             session._websockets.clear()
-        
+
         # Attach new WebSocket
         session.attach_websocket(websocket)
-        
+
         # Replay buffer
         buffer = session.get_buffer()
         if buffer:
             try:
                 await websocket.send_bytes(buffer)
             except Exception:
-                pass
+                pass  # noqa: S110
 
     async def detach_websocket(
         self,
@@ -128,23 +347,60 @@ class TerminalManager:
         instance_id: uuid.UUID,
         container_id: str,
         startup_command: str | None = None,
+        session_id: str | None = None,
+        name: str | None = None,
     ) -> TerminalSession:
-        """Reset a session by killing it and creating a new one."""
+        """Reset a session by killing it and creating a new one.
+
+        Args:
+            instance_id: UUID of the tool instance.
+            container_id: Docker container ID.
+            startup_command: Optional startup command.
+            session_id: Specific session to reset. If None, resets the default session.
+            name: Optional name to preserve for the new session.
+
+        Returns:
+            The newly created TerminalSession.
+        """
         instance_id_str = str(instance_id)
-        
+        target_session_id = session_id or "default"
+        key = (instance_id_str, target_session_id)
+
+        # Preserve old name if not provided
+        old_name = name
+        if old_name is None and key in self._sessions:
+            old_name = self._sessions[key].name
+
         # Close existing session if any
-        if instance_id_str in self._sessions:
-            logger.debug("Resetting terminal session for instance %s", instance_id)
-            old_session = self._sessions.pop(instance_id_str)
+        if key in self._sessions:
+            logger.debug(
+                "Resetting terminal session %s for instance %s",
+                target_session_id,
+                instance_id,
+            )
+            old_session = self._sessions.pop(key)
             await old_session.close()
-        
-        # Create new session
-        session_id = str(uuid.uuid4())
-        session = TerminalSession(session_id, instance_id, container_id, startup_command=startup_command)
-        await session.start(startup_command=startup_command)
-        self._sessions[instance_id_str] = session
-        
-        return session
+            # Fire-and-forget DB update for old session
+            asyncio.create_task(self._mark_closed_in_db(old_session.session_id))
+
+        # Create new session preserving the same session_id slot
+        new_session_id = str(uuid.uuid4())
+        new_session = TerminalSession(
+            session_id=new_session_id,
+            instance_id=instance_id,
+            container_id=container_id,
+            startup_command=startup_command,
+            name=old_name or ("Session 1" if target_session_id == "default" else None),
+        )
+        await new_session.start(startup_command=startup_command)
+        self._sessions[key] = new_session
+
+        # Fire-and-forget DB insert
+        asyncio.create_task(
+            self._insert_db_session_row(new_session_id, instance_id, new_session.name)
+        )
+
+        return new_session
 
     async def close_all(self) -> None:
         """Close all active sessions."""
@@ -152,7 +408,7 @@ class TerminalManager:
         self._sessions.clear()
         for session in sessions:
             await session.close()
-        
+
         if self._idle_check_task and not self._idle_check_task.done():
             self._idle_check_task.cancel()
 

apps/api/src/services/terminal_session.py

@@ -18,18 +18,28 @@ logger = logging.getLogger(__name__)
 
 class TerminalSession:
     """Manages a single terminal session connected to a docker container.
-    
+
     Supports persistent sessions that survive WebSocket disconnections.
     Multiple WebSocket connections can attach/detach from the same session.
     """
 
     # Circular buffer size (10KB)
     BUFFER_SIZE = 10 * 1024
-    
+
     # Idle timeout in seconds (30 minutes)
     IDLE_TIMEOUT = 30 * 60
 
-    def __init__(self, session_id: str, instance_id: uuid.UUID, container_id: str, startup_command: str | None = None) -> None:
+    # Session number counter per instance_id for auto-naming
+    _instance_counters: dict[str, int] = {}
+
+    def __init__(
+        self,
+        session_id: str,
+        instance_id: uuid.UUID,
+        container_id: str,
+        startup_command: str | None = None,
+        name: str | None = None,
+    ) -> None:
         self.session_id = session_id
         self.instance_id = instance_id
         self.container_id = container_id
@@ -38,37 +48,52 @@ class TerminalSession:
         self._closed = False
         self._master_fd: int | None = None
         self._slave_fd: int | None = None
-        
+
         # Circular buffer for output replay
         self._output_buffer: deque[bytes] = deque(maxlen=self.BUFFER_SIZE)
         self._buffer_size = 0
-        
+
         # WebSocket connections
         self._websockets: set[Any] = set()
-        
+
         # Activity tracking
         self.last_activity = time.time()
-        
+
         # Terminal size
         self._cols = 80
         self._rows = 24
 
+        # Session metadata
+        self.name = name or self._generate_name(str(instance_id))
+        self.status: str = "active"
+
+    @classmethod
+    def _generate_name(cls, instance_id: str) -> str:
+        """Generate an auto-incremented session name for the instance."""
+        count = cls._instance_counters.get(instance_id, 0) + 1
+        cls._instance_counters[instance_id] = count
+        return f"Session {count}"
+
     async def start(self, startup_command: str | None = None) -> None:
         """Start the docker exec process with a shell using a PTY."""
         # Create a pseudo-terminal on the host
         self._master_fd, self._slave_fd = pty.openpty()
-        
+
         # Set the terminal size initially
         self._set_terminal_size(self._cols, self._rows)
-        logger.debug(f"Starting terminal session {self.session_id} for container {self.container_id} with initial size {self._cols}x{self._rows}")
-        
+        logger.debug(
+            f"Starting terminal session {self.session_id} for container {self.container_id} with initial size {self._cols}x{self._rows}"
+        )
+
         # Build the shell command
         if startup_command:
             shell_cmd = f'bash -c "{startup_command}" || true; exec bash -il'
-            logger.debug(f"Using startup command for session {self.session_id}: {startup_command}")
+            logger.debug(
+                f"Using startup command for session {self.session_id}: {startup_command}"
+            )
         else:
             shell_cmd = "bash -il"
-        
+
         # Start docker exec with the slave fd as stdin/stdout/stderr
         # Using -it because the slave fd IS a TTY
         self.process = await asyncio.create_subprocess_exec(
@@ -85,11 +110,11 @@ class TerminalSession:
             stdout=self._slave_fd,
             stderr=self._slave_fd,
         )
-        
+
         # Close slave fd in parent process
         os.close(self._slave_fd)
         self._slave_fd = None
-        
+
         self.last_activity = time.time()
 
     def _set_terminal_size(self, cols: int, rows: int) -> None:
@@ -99,7 +124,7 @@ class TerminalSession:
             return
         # TIOCSWINSZ = 0x5414 on Linux
         TIOCSWINSZ = 0x5414
-        size = struct.pack('HHHH', rows, cols, 0, 0)
+        size = struct.pack("HHHH", rows, cols, 0, 0)
         try:
             fcntl.ioctl(self._master_fd, TIOCSWINSZ, size)
             logger.debug(f"Resized PTY to {cols}x{rows} (fd={self._master_fd})")
@@ -127,7 +152,7 @@ class TerminalSession:
         """Add data to circular buffer, maintaining size limit."""
         self._output_buffer.append(data)
         self._buffer_size += len(data)
-        
+
         # Trim if exceeds max size
         while self._buffer_size > self.BUFFER_SIZE and self._output_buffer:
             removed = self._output_buffer.popleft()
@@ -152,16 +177,16 @@ class TerminalSession:
         if self._closed:
             logger.warning("Cannot resize: session is closed")
             return
-        
+
         # Only resize if dimensions actually changed
         if cols == self._cols and rows == self._rows:
             return
-            
+
         self._cols = cols
         self._rows = rows
         logger.debug(f"resize() called for session {self.session_id}: {cols}x{rows}")
         self._set_terminal_size(cols, rows)
-        
+
         # Docker exec -it creates its own PTY inside the container,
         # so host PTY resize doesn't propagate to the container shell.
         # Send SIGWINCH to the docker exec process on the host.
@@ -170,14 +195,19 @@ class TerminalSession:
         if self.process and self.process.pid:
             try:
                 os.kill(self.process.pid, signal.SIGWINCH)
-                logger.debug(f"Sent SIGWINCH to docker exec process {self.process.pid} for session {self.session_id}")
+                logger.debug(
+                    f"Sent SIGWINCH to docker exec process {self.process.pid} for session {self.session_id}"
+                )
             except ProcessLookupError:
-                logger.warning(f"docker exec process {self.process.pid} not found for session {self.session_id}")
+                logger.warning(
+                    f"docker exec process {self.process.pid} not found for session {self.session_id}"
+                )
             except Exception as e:
                 logger.warning(f"Failed to send SIGWINCH: {e}")
 
     async def reset(self) -> None:
         """Reset the session by killing the process and clearing state."""
+        self.status = "resetting"
         await self.close()
         self._closed = False
         self._output_buffer.clear()
@@ -186,18 +216,20 @@ class TerminalSession:
         self.process = None
         self._master_fd = None
         self._slave_fd = None
+        self.status = "active"
 
     async def close(self) -> None:
         """Close the session and cleanup."""
         if self._closed:
             return
         self._closed = True
+        self.status = "closed"
 
         if self._master_fd is not None:
             try:
                 os.close(self._master_fd)
             except OSError:
-                pass
+                pass  # noqa: S110
             self._master_fd = None
 
         if self.process is not None:
@@ -240,7 +272,7 @@ class TerminalSession:
                 await ws.send_bytes(data)
             except Exception:
                 dead_sockets.add(ws)
-        
+
         # Clean up dead sockets
         for ws in dead_sockets:
             self._websockets.discard(ws)

apps/api/tests/api/test_terminal_ws_multi.py

@@ -0,0 +1,67 @@
+"""Integration tests for multi-session terminal WebSocket and REST API."""
+
+import pytest
+from fastapi.testclient import TestClient
+from src.main import app
+
+
+@pytest.fixture
+def client():
+    return TestClient(app)
+
+
+class TestTerminalWebSocketMultiSession:
+    """Tests for multi-session WebSocket routing."""
+
+    def test_specific_session_websocket_route_exists(self, client):
+        """The specific session WebSocket route should be registered."""
+        # We can't easily test WebSocket without auth, but we can verify
+        # the route exists by checking for a 403 (no auth cookie)
+        response = client.get("/ws/tool-instances/test-instance/terminal/test-session")
+        # WebSocket endpoint returns 403 when accessed via HTTP GET
+        assert response.status_code in (403, 404)
+
+    def test_default_session_alias_route_exists(self, client):
+        """The default session alias route should still exist."""
+        response = client.get("/ws/tool-instances/test-instance/terminal")
+        assert response.status_code in (403, 404)
+
+
+class TestTerminalRestApi:
+    """Tests for REST API endpoints."""
+
+    def test_list_sessions_requires_auth(self, client):
+        """List sessions endpoint requires authentication."""
+        response = client.get("/instances/test/terminal/sessions")
+        assert response.status_code == 401
+
+    def test_create_session_requires_auth(self, client):
+        """Create session endpoint requires authentication."""
+        response = client.post(
+            "/instances/test/terminal/sessions",
+            json={},
+        )
+        assert response.status_code == 401
+
+    def test_close_session_requires_auth(self, client):
+        """Close session endpoint requires authentication."""
+        response = client.delete("/instances/test/terminal/sessions/test-session")
+        assert response.status_code == 401
+
+    def test_reset_session_requires_auth(self, client):
+        """Reset session endpoint requires authentication."""
+        response = client.post("/instances/test/terminal/sessions/test-session/reset")
+        assert response.status_code == 401
+
+    def test_rename_session_requires_auth(self, client):
+        """Rename session endpoint requires authentication."""
+        response = client.post(
+            "/instances/test/terminal/sessions/test-session/rename",
+            json={"name": "New Name"},
+        )
+        assert response.status_code == 401
+
+    def test_legacy_reset_alias_requires_auth(self, client):
+        """Legacy reset endpoint still requires auth."""
+        response = client.post("/instances/test/terminal/reset")
+        assert response.status_code == 401

apps/api/tests/integration/test_config_folders_api.py

@@ -1,255 +0,0 @@
-import uuid
-import pytest
-from fastapi.testclient import TestClient
-
-
-@pytest.mark.integration
-class TestConfigFoldersAPI:
-    """Integration tests for config folders API."""
-
-    def test_list_config_folders_requires_authentication(self, test_client: TestClient) -> None:
-        """Test that listing config folders requires authentication."""
-        response = test_client.get("/config-folders")
-        assert response.status_code == 401
-
-    def test_list_config_folders_returns_user_folders(self, authenticated_client: TestClient) -> None:
-        """Test that authenticated users can list their folders."""
-        response = authenticated_client.get("/config-folders")
-        assert response.status_code == 200
-        data = response.json()
-        assert isinstance(data, dict)
-        assert "folders" in data
-        assert isinstance(data["folders"], list)
-
-    def test_create_config_folder_successfully(self, authenticated_client: TestClient) -> None:
-        """Test creating a config folder."""
-        response = authenticated_client.post(
-            "/config-folders",
-            json={
-                "name": "test-folder",
-                "description": "Test folder",
-                "mount_path": "/home/user",
-                "files": {"test.txt": "hello world"},
-            },
-        )
-        assert response.status_code == 201
-        data = response.json()
-        assert data["name"] == "test-folder"
-        assert data["mount_path"] == "/home/user"
-        assert data["files"] == {"test.txt": "hello world"}
-
-    def test_create_config_folder_duplicate_name(self, authenticated_client: TestClient) -> None:
-        """Test that duplicate folder names are rejected."""
-        # Create first folder
-        response = authenticated_client.post(
-            "/config-folders",
-            json={
-                "name": "duplicate-folder",
-                "mount_path": "/home/user",
-                "files": {},
-            },
-        )
-        assert response.status_code == 201
-
-        # Try to create second with same name
-        response = authenticated_client.post(
-            "/config-folders",
-            json={
-                "name": "duplicate-folder",
-                "mount_path": "/home/user",
-                "files": {},
-            },
-        )
-        assert response.status_code == 409
-
-    def test_create_config_folder_exceeds_size_limit(self, authenticated_client: TestClient) -> None:
-        """Test that folders exceeding 10MB are rejected."""
-        large_content = "x" * (11 * 1024 * 1024)  # 11MB
-        response = authenticated_client.post(
-            "/config-folders",
-            json={
-                "name": "large-folder",
-                "mount_path": "/home/user",
-                "files": {"large.txt": large_content},
-            },
-        )
-        assert response.status_code == 422
-
-    def test_create_config_folder_path_traversal_attack(self, authenticated_client: TestClient) -> None:
-        """Test that path traversal in file paths is prevented."""
-        response = authenticated_client.post(
-            "/config-folders",
-            json={
-                "name": "bad-folder",
-                "mount_path": "/home/user",
-                "files": {"../../../etc/passwd": "malicious"},
-            },
-        )
-        assert response.status_code == 422
-
-    def test_get_config_folder_by_id(self, authenticated_client: TestClient) -> None:
-        """Test getting a config folder by ID."""
-        # Create folder first
-        create_response = authenticated_client.post(
-            "/config-folders",
-            json={
-                "name": "get-test",
-                "mount_path": "/home/user",
-                "files": {},
-            },
-        )
-        folder_id = create_response.json()["id"]
-
-        # Get it back
-        response = authenticated_client.get(f"/config-folders/{folder_id}")
-        assert response.status_code == 200
-        data = response.json()
-        assert data["name"] == "get-test"
-
-    def test_get_config_folder_not_found(self, authenticated_client: TestClient) -> None:
-        """Test getting a non-existent folder."""
-        response = authenticated_client.get(f"/config-folders/{uuid.uuid4()}")
-        assert response.status_code == 404
-
-    def test_update_config_folder_successfully(self, authenticated_client: TestClient) -> None:
-        """Test updating a config folder."""
-        # Create folder first
-        create_response = authenticated_client.post(
-            "/config-folders",
-            json={
-                "name": "update-test",
-                "mount_path": "/home/user",
-                "files": {},
-            },
-        )
-        folder_id = create_response.json()["id"]
-
-        # Update it
-        response = authenticated_client.put(
-            f"/config-folders/{folder_id}",
-            json={
-                "name": "updated-name",
-                "mount_path": "/workspace",
-                "files": {"new.txt": "content"},
-            },
-        )
-        assert response.status_code == 200
-        data = response.json()
-        assert data["name"] == "updated-name"
-        assert data["mount_path"] == "/workspace"
-
-    def test_delete_config_folder_successfully(self, authenticated_client: TestClient) -> None:
-        """Test deleting a config folder."""
-        # Create folder first
-        create_response = authenticated_client.post(
-            "/config-folders",
-            json={
-                "name": "delete-test",
-                "mount_path": "/home/user",
-                "files": {},
-            },
-        )
-        folder_id = create_response.json()["id"]
-
-        # Delete it
-        response = authenticated_client.delete(f"/config-folders/{folder_id}")
-        assert response.status_code == 204
-
-        # Verify it's gone
-        get_response = authenticated_client.get(f"/config-folders/{folder_id}")
-        assert get_response.status_code == 404
-
-    def test_add_project_override_successfully(self, authenticated_client: TestClient) -> None:
-        """Test adding a project override."""
-        # Create folder first
-        create_response = authenticated_client.post(
-            "/config-folders",
-            json={
-                "name": "override-test",
-                "mount_path": "/home/user",
-                "files": {"global.txt": "global"},
-            },
-        )
-        folder_id = create_response.json()["id"]
-        project_id = str(uuid.uuid4())
-
-        # Add override
-        response = authenticated_client.post(
-            f"/config-folders/{folder_id}/overrides",
-            json={
-                "project_id": project_id,
-                "mount_path": "/workspace",
-                "files": {"project.txt": "project"},
-            },
-        )
-        assert response.status_code == 200
-        data = response.json()
-        assert project_id in data["project_overrides"]
-
-    def test_update_project_override_successfully(self, authenticated_client: TestClient) -> None:
-        """Test updating a project override."""
-        # Create folder with override
-        create_response = authenticated_client.post(
-            "/config-folders",
-            json={
-                "name": "update-override-test",
-                "mount_path": "/home/user",
-                "files": {},
-            },
-        )
-        folder_id = create_response.json()["id"]
-        project_id = str(uuid.uuid4())
-
-        # Add override
-        authenticated_client.post(
-            f"/config-folders/{folder_id}/overrides",
-            json={
-                "project_id": project_id,
-                "mount_path": "/workspace",
-                "files": {"old.txt": "old"},
-            },
-        )
-
-        # Update override
-        response = authenticated_client.put(
-            f"/config-folders/{folder_id}/overrides/{project_id}",
-            json={
-                "mount_path": "/app",
-                "files": {"new.txt": "new"},
-            },
-        )
-        assert response.status_code == 200
-        data = response.json()
-        assert data["project_overrides"][project_id]["mount_path"] == "/app"
-
-    def test_delete_project_override_successfully(self, authenticated_client: TestClient) -> None:
-        """Test deleting a project override."""
-        # Create folder with override
-        create_response = authenticated_client.post(
-            "/config-folders",
-            json={
-                "name": "delete-override-test",
-                "mount_path": "/home/user",
-                "files": {},
-            },
-        )
-        folder_id = create_response.json()["id"]
-        project_id = str(uuid.uuid4())
-
-        # Add override
-        authenticated_client.post(
-            f"/config-folders/{folder_id}/overrides",
-            json={
-                "project_id": project_id,
-                "mount_path": "/workspace",
-                "files": {},
-            },
-        )
-
-        # Delete override
-        response = authenticated_client.delete(
-            f"/config-folders/{folder_id}/overrides/{project_id}"
-        )
-        assert response.status_code == 200
-        data = response.json()
-        assert project_id not in data["project_overrides"]

apps/api/tests/integration/test_tool_configs_api_extended.py

@@ -1,255 +0,0 @@
-import pytest
-from fastapi.testclient import TestClient
-
-
-@pytest.mark.integration
-class TestToolConfigsAPIExtended:
-    """Integration tests for tool configs API with new fields."""
-
-    def test_create_tool_config_with_new_fields(self, authenticated_client: TestClient) -> None:
-        """Test creating a tool config with all new fields."""
-        # Create a tool type first
-        tool_response = authenticated_client.post(
-            "/tool-types",
-            json={
-                "name": "config-test-tool",
-                "display_name": "Config Test Tool",
-                "default_port": 8080,
-                "definition_type": "compose",
-                "compose_template": "version: '3.8'\nservices:\n  app:\n    image: nginx",
-                "required_variables": [],
-            },
-        )
-        tool_id = tool_response.json()["id"]
-
-        # Create config with new fields
-        response = authenticated_client.post(
-            "/tool-configs",
-            json={
-                "tool_type_id": tool_id,
-                "key": "ADVANCED_CONFIG",
-                "value": "test-value",
-                "config_type": "env",
-                "port_override": 9090,
-                "start_command": "python app.py",
-                "working_directory": "/app",
-                "environment_variables": {"DEBUG": "true", "LOG_LEVEL": "debug"},
-                "volumes": [
-                    {"source": "data", "target": "/data", "type": "bind"}
-                ],
-            },
-        )
-        assert response.status_code == 201
-        data = response.json()
-        assert data["key"] == "ADVANCED_CONFIG"
-        assert data["port_override"] == 9090
-        assert data["start_command"] == "python app.py"
-        assert data["working_directory"] == "/app"
-        assert data["environment_variables"] == {"DEBUG": "true", "LOG_LEVEL": "debug"}
-        assert data["volumes"] == [{"source": "data", "target": "/data", "type": "bind"}]
-
-    def test_create_tool_config_invalid_port(self, authenticated_client: TestClient) -> None:
-        """Test that invalid port numbers are rejected."""
-        # Create a tool type first
-        tool_response = authenticated_client.post(
-            "/tool-types",
-            json={
-                "name": "port-test-tool",
-                "display_name": "Port Test Tool",
-                "default_port": 8080,
-                "definition_type": "compose",
-                "compose_template": "version: '3.8'\nservices:\n  app:\n    image: nginx",
-                "required_variables": [],
-            },
-        )
-        tool_id = tool_response.json()["id"]
-
-        # Try to create config with invalid port
-        response = authenticated_client.post(
-            "/tool-configs",
-            json={
-                "tool_type_id": tool_id,
-                "key": "BAD_PORT",
-                "value": "test",
-                "config_type": "env",
-                "port_override": 99999,
-            },
-        )
-        assert response.status_code == 422
-
-    def test_create_tool_config_invalid_volume_structure(self, authenticated_client: TestClient) -> None:
-        """Test that invalid volume structures are rejected."""
-        # Create a tool type first
-        tool_response = authenticated_client.post(
-            "/tool-types",
-            json={
-                "name": "volume-test-tool",
-                "display_name": "Volume Test Tool",
-                "default_port": 8080,
-                "definition_type": "compose",
-                "compose_template": "version: '3.8'\nservices:\n  app:\n    image: nginx",
-                "required_variables": [],
-            },
-        )
-        tool_id = tool_response.json()["id"]
-
-        # Try to create config with invalid volume
-        response = authenticated_client.post(
-            "/tool-configs",
-            json={
-                "tool_type_id": tool_id,
-                "key": "BAD_VOLUME",
-                "value": "test",
-                "config_type": "env",
-                "volumes": [{"invalid": "structure"}],
-            },
-        )
-        assert response.status_code == 422
-
-    def test_update_tool_config_with_new_fields(self, authenticated_client: TestClient) -> None:
-        """Test updating a tool config with new fields."""
-        # Create a tool type first
-        tool_response = authenticated_client.post(
-            "/tool-types",
-            json={
-                "name": "update-config-tool",
-                "display_name": "Update Config Tool",
-                "default_port": 8080,
-                "definition_type": "compose",
-                "compose_template": "version: '3.8'\nservices:\n  app:\n    image: nginx",
-                "required_variables": [],
-            },
-        )
-        tool_id = tool_response.json()["id"]
-
-        # Create config
-        create_response = authenticated_client.post(
-            "/tool-configs",
-            json={
-                "tool_type_id": tool_id,
-                "key": "UPDATE_TEST",
-                "value": "original",
-                "config_type": "env",
-            },
-        )
-        config_id = create_response.json()["id"]
-
-        # Update with new fields
-        response = authenticated_client.put(
-            f"/tool-configs/{config_id}",
-            json={
-                "value": "updated",
-                "port_override": 3000,
-                "start_command": "npm start",
-                "working_directory": "/workspace",
-                "environment_variables": {"NODE_ENV": "production"},
-                "volumes": [{"source": "src", "target": "/app/src", "type": "bind"}],
-            },
-        )
-        assert response.status_code == 200
-        data = response.json()
-        assert data["value"] == "updated"
-        assert data["port_override"] == 3000
-        assert data["start_command"] == "npm start"
-        assert data["working_directory"] == "/workspace"
-        assert data["environment_variables"] == {"NODE_ENV": "production"}
-
-    def test_list_tool_configs_returns_new_fields(self, authenticated_client: TestClient) -> None:
-        """Test that listing configs returns new fields."""
-        # Create a tool type first
-        tool_response = authenticated_client.post(
-            "/tool-types",
-            json={
-                "name": "list-config-tool",
-                "display_name": "List Config Tool",
-                "default_port": 8080,
-                "definition_type": "compose",
-                "compose_template": "version: '3.8'\nservices:\n  app:\n    image: nginx",
-                "required_variables": [],
-            },
-        )
-        tool_id = tool_response.json()["id"]
-
-        # Create config with new fields
-        authenticated_client.post(
-            "/tool-configs",
-            json={
-                "tool_type_id": tool_id,
-                "key": "LIST_TEST",
-                "value": "test",
-                "config_type": "env",
-                "port_override": 5000,
-                "environment_variables": {"TEST": "true"},
-            },
-        )
-
-        # List configs
-        response = authenticated_client.get("/tool-configs")
-        assert response.status_code == 200
-        data = response.json()
-        assert len(data) > 0
-        config = data[0]
-        assert "port_override" in config
-        assert "start_command" in config
-        assert "working_directory" in config
-        assert "environment_variables" in config
-        assert "volumes" in config
-
-    def test_get_tool_config_defaults(self, authenticated_client: TestClient) -> None:
-        """Test getting tool config defaults."""
-        # Create a tool type first
-        tool_response = authenticated_client.post(
-            "/tool-types",
-            json={
-                "name": "defaults-tool",
-                "display_name": "Defaults Tool",
-                "default_port": 8080,
-                "definition_type": "compose",
-                "compose_template": "version: '3.8'\nservices:\n  app:\n    image: nginx\n    volumes:\n      - \"{{REPO_PATH}}:/workspace\"\n",
-                "required_variables": ["REPO_PATH"],
-            },
-        )
-        tool_id = tool_response.json()["id"]
-
-        # Get defaults
-        response = authenticated_client.get(f"/tool-configs/defaults/{tool_id}")
-        assert response.status_code == 200
-        data = response.json()
-        assert data["tool_type_id"] == tool_id
-        assert "suggested_configs" in data
-
-    def test_tool_config_backward_compatibility(self, authenticated_client: TestClient) -> None:
-        """Test that old configs without new fields still work."""
-        # Create a tool type first
-        tool_response = authenticated_client.post(
-            "/tool-types",
-            json={
-                "name": "backward-compat-tool",
-                "display_name": "Backward Compat Tool",
-                "default_port": 8080,
-                "definition_type": "compose",
-                "compose_template": "version: '3.8'\nservices:\n  app:\n    image: nginx",
-                "required_variables": [],
-            },
-        )
-        tool_id = tool_response.json()["id"]
-
-        # Create config without new fields (simulating old client)
-        response = authenticated_client.post(
-            "/tool-configs",
-            json={
-                "tool_type_id": tool_id,
-                "key": "OLD_STYLE",
-                "value": "value",
-                "config_type": "env",
-            },
-        )
-        assert response.status_code == 201
-        data = response.json()
-        assert data["key"] == "OLD_STYLE"
-        # New fields should have default values
-        assert data["port_override"] is None
-        assert data["start_command"] is None
-        assert data["working_directory"] is None
-        assert data["environment_variables"] is None
-        assert data["volumes"] is None

apps/api/tests/services/test_terminal_manager_multi.py

@@ -0,0 +1,203 @@
+"""Unit tests for TerminalManager multi-session support."""
+
+import asyncio
+import uuid
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from src.services.terminal_manager import MaxSessionsExceededError, TerminalManager
+from src.services.terminal_session import TerminalSession
+
+
+@pytest.fixture
+def manager() -> TerminalManager:
+    """Provide a fresh TerminalManager instance for each test."""
+    tm = TerminalManager()
+    # Cancel the background idle check to avoid side effects
+    if tm._idle_check_task and not tm._idle_check_task.done():
+        tm._idle_check_task.cancel()
+    return tm
+
+
+@pytest.fixture
+def mock_terminal_session(monkeypatch) -> None:
+    """Monkeypatch TerminalSession.start and is_alive for unit tests."""
+
+    async def fake_start(self, startup_command=None):
+        self.last_activity = __import__("time").time()
+
+    monkeypatch.setattr(TerminalSession, "start", fake_start)
+    monkeypatch.setattr(TerminalSession, "is_alive", lambda self: True)
+
+
+@pytest.fixture
+def instance_id() -> uuid.UUID:
+    return uuid.uuid4()
+
+
+class FakeWebSocket:
+    """Minimal fake WebSocket for testing attach/detach behavior."""
+
+    def __init__(self, name: str = "ws") -> None:
+        self.name = name
+        self.closed = False
+        self.close_code: int | None = None
+        self.close_reason: str | None = None
+        self._sent: list[bytes] = []
+
+    async def close(self, code: int = 1000, reason: str = "") -> None:
+        self.closed = True
+        self.close_code = code
+        self.close_reason = reason
+
+    async def send_bytes(self, data: bytes) -> None:
+        self._sent.append(data)
+
+
+@pytest.mark.asyncio
+async def test_create_session_increases_count(
+    manager: TerminalManager,
+    mock_terminal_session,
+    instance_id: uuid.UUID,
+) -> None:
+    """Creating sessions increments the per-instance count."""
+    assert len(manager.get_sessions_for_instance(str(instance_id))) == 0
+
+    session1 = await manager.create_session(instance_id, "container-1")
+    assert len(manager.get_sessions_for_instance(str(instance_id))) == 1
+    assert session1.session_id in [
+        s.session_id for s in manager.get_sessions_for_instance(str(instance_id))
+    ]
+
+    session2 = await manager.create_session(instance_id, "container-1")
+    assert len(manager.get_sessions_for_instance(str(instance_id))) == 2
+
+    # Verify sessions are distinct
+    assert session1.session_id != session2.session_id
+
+
+@pytest.mark.asyncio
+async def test_create_session_enforces_max_5(
+    manager: TerminalManager,
+    mock_terminal_session,
+    instance_id: uuid.UUID,
+) -> None:
+    """The 6th session creation raises MaxSessionsExceededError."""
+    for i in range(5):
+        await manager.create_session(instance_id, f"container-{i}")
+
+    assert len(manager.get_sessions_for_instance(str(instance_id))) == 5
+
+    with pytest.raises(MaxSessionsExceededError):
+        await manager.create_session(instance_id, "container-overflow")
+
+
+@pytest.mark.asyncio
+async def test_get_sessions_for_instance_filters_by_instance(
+    manager: TerminalManager,
+    mock_terminal_session,
+) -> None:
+    """get_sessions_for_instance returns only sessions for the requested instance."""
+    instance_a = uuid.uuid4()
+    instance_b = uuid.uuid4()
+
+    await manager.create_session(instance_a, "container-a")
+    await manager.create_session(instance_a, "container-a2")
+    await manager.create_session(instance_b, "container-b")
+
+    assert len(manager.get_sessions_for_instance(str(instance_a))) == 2
+    assert len(manager.get_sessions_for_instance(str(instance_b))) == 1
+
+
+@pytest.mark.asyncio
+async def test_close_session_removes_from_dict(
+    manager: TerminalManager,
+    mock_terminal_session,
+    instance_id: uuid.UUID,
+) -> None:
+    """close_session removes the key from _sessions and marks DB closed."""
+    session = await manager.create_session(instance_id, "container-1")
+    session_id = session.session_id
+
+    assert manager.get_session(str(instance_id), session_id) is not None
+
+    with patch.object(manager, "_mark_closed_in_db", new=AsyncMock()) as mock_mark:
+        await manager.close_session(str(instance_id), session_id)
+        # Give the fire-and-forget task a chance to be scheduled
+        await asyncio.sleep(0)
+
+    assert manager.get_session(str(instance_id), session_id) is None
+    mock_mark.assert_called_once_with(session_id)
+
+
+@pytest.mark.asyncio
+async def test_attach_websocket_only_closes_same_session(
+    manager: TerminalManager,
+    mock_terminal_session,
+    instance_id: uuid.UUID,
+) -> None:
+    """Attaching to session A must not close WebSockets on session B."""
+    session_a = await manager.create_session(instance_id, "container-1")
+    session_b = await manager.create_session(instance_id, "container-1")
+
+    ws_a1 = FakeWebSocket("ws-a1")
+    ws_b1 = FakeWebSocket("ws-b1")
+
+    # Manually attach websockets (simulate prior connections)
+    session_a.attach_websocket(ws_a1)
+    session_b.attach_websocket(ws_b1)
+
+    # Now attach a new websocket to session_a
+    ws_a2 = FakeWebSocket("ws-a2")
+    await manager.attach_websocket(session_a, ws_a2)
+
+    # ws_a1 should have been closed because it's on the same session
+    assert ws_a1.closed is True
+
+    # ws_b1 should NOT have been closed because it's on a different session
+    assert ws_b1.closed is False
+
+    # ws_a2 should be attached and receive buffer
+    assert ws_a2 in session_a._websockets
+
+
+@pytest.mark.asyncio
+async def test_default_session_keyed_separately(
+    manager: TerminalManager,
+    mock_terminal_session,
+    instance_id: uuid.UUID,
+) -> None:
+    """Default session uses 'default' session_id and does not collide with named sessions."""
+    default_session = await manager.get_or_create_session(instance_id, "container-1")
+    explicit_session = await manager.create_session(instance_id, "container-1")
+
+    # Both should exist
+    assert manager.get_session(str(instance_id), "default") is default_session
+    assert (
+        manager.get_session(str(instance_id), explicit_session.session_id)
+        is explicit_session
+    )
+
+    # They should be different objects
+    assert default_session.session_id != explicit_session.session_id
+
+
+@pytest.mark.asyncio
+async def test_idle_cleanup_updates_db_status(
+    manager: TerminalManager,
+    mock_terminal_session,
+    instance_id: uuid.UUID,
+) -> None:
+    """Idle cleanup removes sessions from dict and calls DB update."""
+    session = await manager.create_session(instance_id, "container-1")
+    session_id = session.session_id
+
+    # Make session appear idle (no websockets, old last_activity)
+    session.last_activity = 0
+
+    with patch.object(manager, "_mark_closed_in_db", new=AsyncMock()) as mock_mark:
+        await manager._cleanup_idle_sessions()
+
+    assert manager.get_session(str(instance_id), session_id) is None
+    mock_mark.assert_called_once_with(session_id)

apps/api/tests/unit/test_config_profile_resolver.py

@@ -75,6 +75,7 @@ class TestMergeFunctions:
     def test_merge_mounts_file_override(self) -> None:
         """Test mount file map merging with overrides."""
         from src.services.config_profile_resolver import ResolvedMount
+
         result = _merge_mounts(
             {"/app": ResolvedMount(target="/app", mode="rw", files={"a.txt": "old"})},
             [{"target": "/app", "mode": "rw", "files": {"a.txt": "new"}}],
@@ -86,6 +87,7 @@ class TestMergeFunctions:
     def test_merge_mounts_mode_conflict(self) -> None:
         """Test that mount mode conflicts are resolved (later wins)."""
         from src.services.config_profile_resolver import ResolvedMount
+
         overrides = {}
         result = _merge_mounts(
             {"/app": ResolvedMount(target="/app", mode="rw", files={})},
@@ -97,37 +99,125 @@ class TestMergeFunctions:
         assert overrides == {"/app": "source"}
 
     def test_merge_git_mounts_basic(self) -> None:
-        """Test basic git mount merging."""
+        """Test basic git mount merging normalizes to mappings format."""
         result = _merge_git_mounts(
             [],
-            [{"remote_url": "https://github.com/user/repo1.git", "source_path": ".", "target_path": "/app"}],
+            [
+                {
+                    "remote_url": "https://github.com/user/repo1.git",
+                    "source_path": ".",
+                    "target_path": "/app",
+                }
+            ],
             "source",
         )
         assert len(result) == 1
         assert result[0]["remote_url"] == "https://github.com/user/repo1.git"
-        assert result[0]["target_path"] == "/app"
+        assert "mappings" in result[0]
+        assert result[0]["mappings"] == [{"source_path": ".", "target_path": "/app"}]
 
-    def test_merge_git_mounts_override_same_repo_target(self) -> None:
-        """Test that git mounts with same repo+target override."""
+    def test_merge_git_mounts_concatenate_same_repo_branch(self) -> None:
+        """Test that git mounts with same repo+branch concatenate mappings."""
         result = _merge_git_mounts(
-            [{"remote_url": "https://github.com/user/repo1.git", "source_path": ".", "target_path": "/app", "branch": "main"}],
-            [{"remote_url": "https://github.com/user/repo1.git", "source_path": "src", "target_path": "/app", "branch": "dev"}],
+            [
+                {
+                    "remote_url": "https://github.com/user/repo1.git",
+                    "source_path": ".",
+                    "target_path": "/app",
+                    "branch": "main",
+                }
+            ],
+            [
+                {
+                    "remote_url": "https://github.com/user/repo1.git",
+                    "source_path": "src",
+                    "target_path": "/src",
+                    "branch": "main",
+                }
+            ],
             "source",
         )
         assert len(result) == 1
-        assert result[0]["source_path"] == "src"
-        assert result[0]["branch"] == "dev"
+        assert result[0]["branch"] == "main"
+        mappings: list[dict[str, str]] = result[0]["mappings"]
+        assert len(mappings) == 2
+        assert {"source_path": ".", "target_path": "/app"} in mappings
+        assert {"source_path": "src", "target_path": "/src"} in mappings
 
-    def test_merge_git_mounts_different_targets(self) -> None:
-        """Test that git mounts with different targets are preserved."""
+    def test_merge_git_mounts_dedup_same_mapping(self) -> None:
+        """Test that duplicate mappings are deduplicated."""
         result = _merge_git_mounts(
-            [{"remote_url": "https://github.com/user/repo1.git", "source_path": ".", "target_path": "/app"}],
-            [{"remote_url": "https://github.com/user/repo2.git", "source_path": ".", "target_path": "/config"}],
+            [
+                {
+                    "remote_url": "https://github.com/user/repo1.git",
+                    "source_path": ".",
+                    "target_path": "/app",
+                    "branch": "main",
+                }
+            ],
+            [
+                {
+                    "remote_url": "https://github.com/user/repo1.git",
+                    "source_path": ".",
+                    "target_path": "/app",
+                    "branch": "main",
+                }
+            ],
+            "source",
+        )
+        assert len(result) == 1
+        assert len(result[0]["mappings"]) == 1
+
+    def test_merge_git_mounts_different_repos(self) -> None:
+        """Test that git mounts with different repos are preserved."""
+        result = _merge_git_mounts(
+            [
+                {
+                    "remote_url": "https://github.com/user/repo1.git",
+                    "source_path": ".",
+                    "target_path": "/app",
+                }
+            ],
+            [
+                {
+                    "remote_url": "https://github.com/user/repo2.git",
+                    "source_path": ".",
+                    "target_path": "/config",
+                }
+            ],
             "source",
         )
         assert len(result) == 2
-        targets = {m["target_path"] for m in result}
-        assert targets == {"/app", "/config"}
+        urls = {m["remote_url"] for m in result}
+        assert urls == {
+            "https://github.com/user/repo1.git",
+            "https://github.com/user/repo2.git",
+        }
+
+    def test_merge_git_mounts_different_branches(self) -> None:
+        """Test that same repo with different branches are kept separate."""
+        result = _merge_git_mounts(
+            [
+                {
+                    "remote_url": "https://github.com/user/repo1.git",
+                    "source_path": ".",
+                    "target_path": "/app",
+                    "branch": "main",
+                }
+            ],
+            [
+                {
+                    "remote_url": "https://github.com/user/repo1.git",
+                    "source_path": ".",
+                    "target_path": "/app",
+                    "branch": "dev",
+                }
+            ],
+            "source",
+        )
+        assert len(result) == 2
+        branches = {m.get("branch") for m in result}
+        assert branches == {"main", "dev"}
 
 
 class TestResolveProfile:
@@ -156,7 +246,9 @@ class TestResolveProfile:
         assert result.files == {"test.txt": "content"}
 
     @pytest.mark.asyncio
-    async def test_resolve_profile_with_includes(self, db_session: AsyncSession) -> None:
+    async def test_resolve_profile_with_includes(
+        self, db_session: AsyncSession
+    ) -> None:
         """Test resolving a profile that includes another."""
         user_id = uuid.uuid4()
 
@@ -200,7 +292,9 @@ class TestResolveProfile:
         assert result.included_profiles[0]["name"] == "base"
 
     @pytest.mark.asyncio
-    async def test_resolve_profile_child_overrides_parent(self, db_session: AsyncSession) -> None:
+    async def test_resolve_profile_child_overrides_parent(
+        self, db_session: AsyncSession
+    ) -> None:
         """Test that child profile values override parent values."""
         user_id = uuid.uuid4()
 
@@ -237,7 +331,9 @@ class TestResolveProfile:
         assert result.env_overrides == {"VAR": "child"}
 
     @pytest.mark.asyncio
-    async def test_resolve_profile_cycle_detection(self, db_session: AsyncSession) -> None:
+    async def test_resolve_profile_cycle_detection(
+        self, db_session: AsyncSession
+    ) -> None:
         """Test that cycles are detected during resolution."""
         user_id = uuid.uuid4()
 
@@ -283,10 +379,12 @@ class TestResolveProfile:
             await resolve_profile(db_session, profile_a.id)
 
     @pytest.mark.asyncio
-    async def test_resolve_profile_with_git_mounts(self, db_session: AsyncSession) -> None:
-        """Test resolving a profile with git mounts."""
+    async def test_resolve_profile_with_git_mounts(
+        self, db_session: AsyncSession
+    ) -> None:
+        """Test resolving a profile with git mounts normalizes to mappings."""
         user_id = uuid.uuid4()
-        
+
         profile = ConfigProfile(
             id=uuid.uuid4(),
             user_id=user_id,
@@ -294,22 +392,31 @@ class TestResolveProfile:
             env_vars={},
             files={},
             git_mounts=[
-                {"remote_url": "https://github.com/user/repo1.git", "source_path": ".", "target_path": "/app"},
+                {
+                    "remote_url": "https://github.com/user/repo1.git",
+                    "source_path": ".",
+                    "target_path": "/app",
+                },
             ],
         )
         db_session.add(profile)
         await db_session.commit()
-        
+
         result = await resolve_profile(db_session, profile.id)
         assert len(result.git_mounts) == 1
         assert result.git_mounts[0]["remote_url"] == "https://github.com/user/repo1.git"
-        assert result.git_mounts[0]["target_path"] == "/app"
-    
+        assert "mappings" in result.git_mounts[0]
+        assert result.git_mounts[0]["mappings"] == [
+            {"source_path": ".", "target_path": "/app"}
+        ]
+
     @pytest.mark.asyncio
-    async def test_resolve_profile_with_git_mount_includes(self, db_session: AsyncSession) -> None:
+    async def test_resolve_profile_with_git_mount_includes(
+        self, db_session: AsyncSession
+    ) -> None:
         """Test resolving a profile that includes another with git mounts."""
         user_id = uuid.uuid4()
-        
+
         # Create base profile with git mount
         base = ConfigProfile(
             id=uuid.uuid4(),
@@ -318,11 +425,15 @@ class TestResolveProfile:
             env_vars={},
             files={},
             git_mounts=[
-                {"remote_url": "https://github.com/user/repo1.git", "source_path": ".", "target_path": "/app"},
+                {
+                    "remote_url": "https://github.com/user/repo1.git",
+                    "source_path": ".",
+                    "target_path": "/app",
+                },
             ],
         )
         db_session.add(base)
-        
+
         # Create child profile with its own git mount
         child = ConfigProfile(
             id=uuid.uuid4(),
@@ -331,12 +442,16 @@ class TestResolveProfile:
             env_vars={},
             files={},
             git_mounts=[
-                {"remote_url": "https://github.com/user/repo2.git", "source_path": "config", "target_path": "/config"},
+                {
+                    "remote_url": "https://github.com/user/repo2.git",
+                    "source_path": "config",
+                    "target_path": "/config",
+                },
             ],
         )
         db_session.add(child)
         await db_session.commit()
-        
+
         # Create include relationship
         include = ConfigProfileInclude(
             id=uuid.uuid4(),
@@ -346,11 +461,16 @@ class TestResolveProfile:
         )
         db_session.add(include)
         await db_session.commit()
-        
+
         result = await resolve_profile(db_session, child.id)
         assert len(result.git_mounts) == 2
-        targets = {m["target_path"] for m in result.git_mounts}
-        assert targets == {"/app", "/config"}
+        urls = {m["remote_url"] for m in result.git_mounts}
+        assert urls == {
+            "https://github.com/user/repo1.git",
+            "https://github.com/user/repo2.git",
+        }
+        for m in result.git_mounts:
+            assert "mappings" in m
 
     @pytest.mark.asyncio
     async def test_resolve_profile_not_found(self, db_session: AsyncSession) -> None:

apps/api/tests/unit/test_git_mounts.py

@@ -0,0 +1,219 @@
+"""Unit tests for git mount resolution with multi-mapping support."""
+
+import os
+import tempfile
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from src.api.tool_instances import (
+    _clone_git_repo,
+    _expand_glob_source,
+    _normalize_git_mount,
+    _resolve_git_mount_mappings,
+    _resolve_single_git_mount,
+)
+
+
+class TestNormalizeGitMount:
+    """Tests for _normalize_git_mount."""
+
+    def test_legacy_to_mappings(self) -> None:
+        """Legacy source_path + target_path becomes mappings array."""
+        entry = {
+            "remote_url": "https://github.com/user/repo.git",
+            "source_path": "packages/api",
+            "target_path": "/app/api",
+            "branch": "main",
+        }
+        result = _normalize_git_mount(entry)
+        assert "mappings" in result
+        assert result["mappings"] == [
+            {"source_path": "packages/api", "target_path": "/app/api"}
+        ]
+        assert "source_path" not in result
+        assert "target_path" not in result
+        assert result["remote_url"] == "https://github.com/user/repo.git"
+        assert result["branch"] == "main"
+
+    def test_already_mappings(self) -> None:
+        """Entry already with mappings is left unchanged."""
+        entry = {
+            "remote_url": "https://github.com/user/repo.git",
+            "branch": "main",
+            "mappings": [
+                {"source_path": "a", "target_path": "/a"},
+                {"source_path": "b", "target_path": "/b"},
+            ],
+        }
+        result = _normalize_git_mount(entry)
+        assert result["mappings"] == [
+            {"source_path": "a", "target_path": "/a"},
+            {"source_path": "b", "target_path": "/b"},
+        ]
+        assert "source_path" not in result
+        assert "target_path" not in result
+
+    def test_missing_target_path_no_mappings(self) -> None:
+        """Entry with source_path but no target_path creates empty mappings."""
+        entry = {
+            "remote_url": "https://github.com/user/repo.git",
+            "source_path": "src",
+        }
+        result = _normalize_git_mount(entry)
+        assert "mappings" not in result
+
+
+class TestResolveGitMountMappings:
+    """Tests for _resolve_git_mount_mappings."""
+
+    def test_single_mapping(self) -> None:
+        """A single mapping produces one volume mount."""
+        with tempfile.TemporaryDirectory() as repo_path:
+            os.makedirs(os.path.join(repo_path, "packages", "api"))
+            mappings = [
+                {"source_path": "packages/api", "target_path": "/app/api"},
+            ]
+            result = _resolve_git_mount_mappings(repo_path, mappings, None)
+            assert len(result) == 1
+            assert result[0]["source"] == os.path.join(repo_path, "packages", "api")
+            assert result[0]["target"] == "/app/api"
+            assert result[0]["type"] == "bind"
+
+    def test_multiple_mappings(self) -> None:
+        """Multiple mappings from same repo produce multiple mounts."""
+        with tempfile.TemporaryDirectory() as repo_path:
+            os.makedirs(os.path.join(repo_path, "packages", "api"))
+            os.makedirs(os.path.join(repo_path, "packages", "web"))
+            mappings = [
+                {"source_path": "packages/api", "target_path": "/app/api"},
+                {"source_path": "packages/web", "target_path": "/app/web"},
+            ]
+            result = _resolve_git_mount_mappings(repo_path, mappings, None)
+            assert len(result) == 2
+            targets = {r["target"] for r in result}
+            assert targets == {"/app/api", "/app/web"}
+
+    def test_relative_target_path(self) -> None:
+        """Relative target_path is resolved against working_directory."""
+        with tempfile.TemporaryDirectory() as repo_path:
+            os.makedirs(os.path.join(repo_path, "src"))
+            mappings = [
+                {"source_path": "src", "target_path": "code"},
+            ]
+            result = _resolve_git_mount_mappings(repo_path, mappings, "/workspace")
+            assert len(result) == 1
+            assert result[0]["target"] == "/workspace/code"
+
+    def test_glob_expansion(self) -> None:
+        """Glob patterns in source_path are expanded."""
+        with tempfile.TemporaryDirectory() as repo_path:
+            os.makedirs(os.path.join(repo_path, "packages", "api"))
+            os.makedirs(os.path.join(repo_path, "packages", "web"))
+            mappings = [
+                {"source_path": "packages/*", "target_path": "/app/packages"},
+            ]
+            result = _resolve_git_mount_mappings(repo_path, mappings, None)
+            assert len(result) == 2
+            targets = {r["target"] for r in result}
+            assert targets == {
+                os.path.join("/app/packages", "packages", "api"),
+                os.path.join("/app/packages", "packages", "web"),
+            }
+
+    def test_missing_target_path_skipped(self) -> None:
+        """Mapping without target_path is skipped."""
+        with tempfile.TemporaryDirectory() as repo_path:
+            mappings = [
+                {"source_path": "src"},
+            ]
+            result = _resolve_git_mount_mappings(repo_path, mappings, None)
+            assert len(result) == 0
+
+    def test_no_working_directory_for_relative_target(self) -> None:
+        """Relative target without working_directory is skipped."""
+        with tempfile.TemporaryDirectory() as repo_path:
+            os.makedirs(os.path.join(repo_path, "src"))
+            mappings = [
+                {"source_path": "src", "target_path": "code"},
+            ]
+            result = _resolve_git_mount_mappings(repo_path, mappings, None)
+            assert len(result) == 0
+
+
+class TestResolveSingleGitMount:
+    """Tests for _resolve_single_git_mount."""
+
+    @pytest.mark.asyncio
+    async def test_missing_remote_url(self) -> None:
+        """Git mount without remote_url returns empty list."""
+        result = await _resolve_single_git_mount(
+            MagicMock(),
+            {"mappings": [{"source_path": ".", "target_path": "/app"}]},
+            "/tmp",
+            None,
+        )
+        assert result == []
+
+    @pytest.mark.asyncio
+    async def test_missing_instance_dir(self) -> None:
+        """Git mount without instance_dir returns empty list."""
+        result = await _resolve_single_git_mount(
+            MagicMock(),
+            {
+                "remote_url": "https://github.com/user/repo.git",
+                "mappings": [{"source_path": ".", "target_path": "/app"}],
+            },
+            None,
+            None,
+        )
+        assert result == []
+
+    @pytest.mark.asyncio
+    async def test_legacy_format_normalized(self) -> None:
+        """Legacy format is normalized and resolved."""
+        with tempfile.TemporaryDirectory() as instance_dir:
+            with patch(
+                "src.api.tool_instances._clone_git_repo",
+                return_value=os.path.join(instance_dir, "repo-clone"),
+            ):
+                os.makedirs(os.path.join(instance_dir, "repo-clone", "src"))
+                result = await _resolve_single_git_mount(
+                    MagicMock(),
+                    {
+                        "remote_url": "https://github.com/user/repo.git",
+                        "source_path": "src",
+                        "target_path": "/app/src",
+                    },
+                    instance_dir,
+                    None,
+                )
+                assert len(result) == 1
+                assert result[0]["target"] == "/app/src"
+
+
+class TestExpandGlobSource:
+    """Tests for _expand_glob_source."""
+
+    def test_no_glob(self) -> None:
+        """Non-glob path returns single item if exists."""
+        with tempfile.TemporaryDirectory() as tmp:
+            path = os.path.join(tmp, "file.txt")
+            open(path, "w").close()
+            result = _expand_glob_source(path, tmp)
+            assert result == [path]
+
+    def test_no_glob_missing(self) -> None:
+        """Non-glob path that doesn't exist returns empty list."""
+        with tempfile.TemporaryDirectory() as tmp:
+            path = os.path.join(tmp, "missing.txt")
+            result = _expand_glob_source(path, tmp)
+            assert result == []
+
+    def test_glob_pattern(self) -> None:
+        """Glob pattern expands to matched paths."""
+        with tempfile.TemporaryDirectory() as tmp:
+            open(os.path.join(tmp, "a.txt"), "w").close()
+            open(os.path.join(tmp, "b.txt"), "w").close()
+            result = _expand_glob_source(os.path.join(tmp, "*.txt"), tmp)
+            assert len(result) == 2

apps/api/tests/unit/test_home_path_expansion.py

@@ -0,0 +1,99 @@
+"""Unit tests for ~ / $HOME expansion in container paths."""
+
+import pytest
+
+from src.api.tool_instances import _resolve_git_mount_mappings
+from src.services.config_profile_resolver import expand_container_path
+from src.services.manifest_compiler import get_manifest_home_dir
+
+
+class TestExpandContainerPath:
+    """Tests for expand_container_path helper."""
+
+    def test_tilde_slash_expands(self) -> None:
+        """~/foo should expand to home_dir/foo."""
+        assert expand_container_path("~/workspace", "/home/user") == "/home/user/workspace"
+
+    def test_tilde_alone_expands(self) -> None:
+        """~ should expand to home_dir."""
+        assert expand_container_path("~", "/home/user") == "/home/user"
+
+    def test_dollar_home_slash_expands(self) -> None:
+        """$HOME/foo should expand to home_dir/foo."""
+        assert expand_container_path("$HOME/workspace", "/home/user") == "/home/user/workspace"
+
+    def test_dollar_home_alone_expands(self) -> None:
+        """$HOME should expand to home_dir."""
+        assert expand_container_path("$HOME", "/home/user") == "/home/user"
+
+    def test_absolute_path_unchanged(self) -> None:
+        """Absolute paths should not be modified."""
+        assert expand_container_path("/app/workspace", "/home/user") == "/app/workspace"
+
+    def test_relative_path_unchanged(self) -> None:
+        """Relative paths should not be modified."""
+        assert expand_container_path("workspace", "/home/user") == "workspace"
+
+    def test_tilde_in_middle_unchanged(self) -> None:
+        """~ in the middle of a path should not expand."""
+        assert expand_container_path("/app/~user", "/home/user") == "/app/~user"
+
+    def test_dollar_home_in_middle_unchanged(self) -> None:
+        """$HOME in the middle of a path should not expand."""
+        assert expand_container_path("/app/$HOMEuser", "/home/user") == "/app/$HOMEuser"
+
+    def test_root_home(self) -> None:
+        """Expansion works with /root as home."""
+        assert expand_container_path("~/config", "/root") == "/root/config"
+
+
+class TestGetManifestHomeDir:
+    """Tests for get_manifest_home_dir helper."""
+
+    def test_with_user_block(self) -> None:
+        """Manifest with user block returns /home/{name}."""
+        manifest = {"user": {"name": "developer", "uid": 1000, "gid": 1000}}
+        assert get_manifest_home_dir(manifest) == "/home/developer"
+
+    def test_without_user_block(self) -> None:
+        """Manifest without user block returns /root."""
+        manifest = {"base_image": "ubuntu:24.04"}
+        assert get_manifest_home_dir(manifest) == "/root"
+
+    def test_with_empty_user_name(self) -> None:
+        """Manifest with empty user name returns /root."""
+        manifest = {"user": {"name": "", "uid": 1000, "gid": 1000}}
+        assert get_manifest_home_dir(manifest) == "/root"
+
+    def test_with_none_user_name(self) -> None:
+        """Manifest with None user name returns /root."""
+        manifest = {"user": {"name": None, "uid": 1000, "gid": 1000}}
+        assert get_manifest_home_dir(manifest) == "/root"
+
+
+class TestResolveGitMountMappingsExpansion:
+    """Tests that git mount mapping targets expand ~ and $HOME."""
+
+    def test_tilde_target_expansion(self, tmp_path) -> None:
+        """Mapping with ~/repo target expands to home dir."""
+        (tmp_path / "src").mkdir()
+        mappings = [{"source_path": "src", "target_path": "~/repo"}]
+        result = _resolve_git_mount_mappings(str(tmp_path), mappings, None, "/home/user")
+        assert len(result) == 1
+        assert result[0]["target"] == "/home/user/repo"
+
+    def test_dollar_home_target_expansion(self, tmp_path) -> None:
+        """Mapping with $HOME/repo target expands to home dir."""
+        (tmp_path / "src").mkdir()
+        mappings = [{"source_path": "src", "target_path": "$HOME/repo"}]
+        result = _resolve_git_mount_mappings(str(tmp_path), mappings, None, "/home/user")
+        assert len(result) == 1
+        assert result[0]["target"] == "/home/user/repo"
+
+    def test_absolute_target_unchanged(self, tmp_path) -> None:
+        """Absolute target paths are not modified."""
+        (tmp_path / "src").mkdir()
+        mappings = [{"source_path": "src", "target_path": "/app/src"}]
+        result = _resolve_git_mount_mappings(str(tmp_path), mappings, None, "/home/user")
+        assert len(result) == 1
+        assert result[0]["target"] == "/app/src"

apps/api/tests/unit/test_manifest_compiler.py

@@ -8,6 +8,7 @@ from src.services.manifest_compiler import (
     compile_entrypoint,
     compute_image_tag,
     deep_merge,
+    get_manifest_home_dir,
     merge_with_config,
     resolve_base,
 )
@@ -161,6 +162,38 @@ class TestCompileDockerfile:
         df = compile_dockerfile(manifest)
         assert 'CMD ["/bin/bash"]' in df
 
+    def test_sets_home_env_for_user(self) -> None:
+        manifest = {
+            "base_image": "ubuntu:24.04",
+            "name": "test",
+            "user": {"name": "dev", "uid": 1001, "gid": 1001},
+        }
+        df = compile_dockerfile(manifest)
+        assert "ENV HOME=/home/dev" in df
+        assert "ENV USER=dev" in df
+
+    def test_no_home_env_without_user(self) -> None:
+        manifest = {"base_image": "ubuntu:24.04", "name": "test"}
+        df = compile_dockerfile(manifest)
+        assert "ENV HOME=" not in df
+        assert "ENV USER=" not in df
+
+
+class TestGetManifestHomeDir:
+    """Tests for get_manifest_home_dir."""
+
+    def test_with_user_name(self) -> None:
+        manifest = {"user": {"name": "dev", "uid": 1001, "gid": 1001}}
+        assert get_manifest_home_dir(manifest) == "/home/dev"
+
+    def test_without_user(self) -> None:
+        manifest = {"base_image": "ubuntu:24.04"}
+        assert get_manifest_home_dir(manifest) == "/root"
+
+    def test_with_empty_user_name(self) -> None:
+        manifest = {"user": {"name": "", "uid": 1001, "gid": 1001}}
+        assert get_manifest_home_dir(manifest) == "/root"
+
 
 class TestCompileEntrypoint:
     """Tests for compile_entrypoint."""
@@ -292,24 +325,41 @@ class TestComputeImageTag:
 
 
 class TestMergeWithConfig:
-    """Tests for merge_with_config."""
+    """Tests for merge_with_config (ConfigProfile only)."""
 
-    def test_applies_tool_config_env(self) -> None:
+    def test_no_profile_returns_manifest_unchanged(self) -> None:
         manifest = {"name": "test"}
-        configs = [
-            {"config_type": "env", "key": "FOO", "value": "bar"},
-        ]
-        result = merge_with_config(manifest, configs)
+        result = merge_with_config(manifest)
+        assert result["name"] == "test"
+        assert result["_extra_env"] == {}
+        assert result["_extra_volumes"] == []
+
+    def test_profile_env_vars(self) -> None:
+        manifest = {"name": "test"}
+        profile = {"environment_variables": {"FOO": "bar"}}
+        result = merge_with_config(manifest, profile)
         assert result["_extra_env"]["FOO"] == "bar"
 
-    def test_applies_port_override(self) -> None:
+    def test_profile_mounts(self) -> None:
+        manifest = {"name": "test"}
+        profile = {"mounts": [{"source": "/host", "target": "/container"}]}
+        result = merge_with_config(manifest, profile)
+        assert len(result["_extra_volumes"]) == 1
+
+    def test_profile_port_override(self) -> None:
         manifest = {"name": "test", "default_port": 8080}
-        configs = [{"port_override": 3000}]
-        result = merge_with_config(manifest, configs)
+        profile = {"hints": {"port_override": 3000}}
+        result = merge_with_config(manifest, profile)
         assert result["default_port"] == 3000
 
-    def test_applies_start_command(self) -> None:
+    def test_profile_start_command(self) -> None:
         manifest = {"name": "test", "runtime": {"command": ["/bin/bash"]}}
-        configs = [{"start_command": "/bin/sh"}]
-        result = merge_with_config(manifest, configs)
+        profile = {"hints": {"start_command": "/bin/sh"}}
+        result = merge_with_config(manifest, profile)
         assert result["runtime"]["command"] == ["/bin/sh"]
+
+    def test_profile_working_directory(self) -> None:
+        manifest = {"name": "test"}
+        profile = {"hints": {"working_directory": "/workspace"}}
+        result = merge_with_config(manifest, profile)
+        assert result["runtime"]["working_dir"] == "/workspace"

apps/api/tests/unit/test_tool_instances_legacy.py

@@ -735,6 +735,7 @@ class TestStartInstanceManifestBranch:
             "headquarter/test:latest",
             "services:\n  app:\n    image: test",
             {"name": "test-manifest"},
+            "/root",
         )
 
         instance = ToolInstance(

apps/web/.pi-lens/cache/tsx-rules-v2.json

@@ -0,0 +1,36 @@
+{
+  "version": "v2",
+  "timestamp": 1779892231625,
+  "ruleHash": "0a2423849fae7580",
+  "queries": [
+    {
+      "id": "dangerously-set-inner-html",
+      "name": "Dangerously Set Inner HTML",
+      "severity": "error",
+      "language": "tsx",
+      "message": "dangerouslySetInnerHTML — XSS risk, sanitize user input",
+      "query": "  (jsx_attribute\n    (property_identifier) @ATTR\n    (#match? @ATTR \"dangerouslySetInnerHTML\"))",
+      "metavars": [
+        "ATTR"
+      ],
+      "defect_class": "injection",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/tsx/dangerously-set-inner-html.yml"
+    },
+    {
+      "id": "no-nested-links",
+      "name": "Nested anchor tags",
+      "severity": "error",
+      "language": "tsx",
+      "message": "Nested <a> tags are invalid HTML and cause unexpected behavior",
+      "query": "  (jsx_element\n    open_tag: (jsx_opening_element\n      (identifier) @OUTER\n      (#eq? @OUTER \"a\"))\n    (jsx_element\n      open_tag: (jsx_opening_element\n        (identifier) @INNER\n        (#eq? @INNER \"a\"))))",
+      "metavars": [
+        "OUTER",
+        "INNER"
+      ],
+      "defect_class": "correctness",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/tsx/no-nested-links.yml"
+    }
+  ]
+}

apps/web/.pi-lens/cache/typescript-rules-v2.json

@@ -0,0 +1,477 @@
+{
+  "version": "v2",
+  "timestamp": 1779889832502,
+  "ruleHash": "45ab8be323739a4e",
+  "queries": [
+    {
+      "id": "console-statement",
+      "name": "Console Statement",
+      "severity": "warning",
+      "language": "typescript",
+      "message": "{{METHOD}} — remove debug statements before committing",
+      "query": "  (call_expression\n    function: (member_expression\n      object: (identifier) @OBJ (#eq? @OBJ \"console\")\n      property: (property_identifier) @METHOD (#not-eq? @METHOD \"dbg\"))\n    arguments: (arguments) @ARGS)",
+      "metavars": [
+        "OBJ",
+        "METHOD",
+        "ARGS"
+      ],
+      "post_filter": "not_in_test_block  # skip test blocks — no-console-in-tests handles that case",
+      "defect_class": "safety",
+      "inline_tier": "warning",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/typescript/console-statement.yml"
+    },
+    {
+      "id": "debugger-statement",
+      "name": "Debugger Statement",
+      "severity": "error",
+      "language": "typescript",
+      "message": "Debugger statement — remove before committing",
+      "query": "  (debugger_statement) @DEBUGGER",
+      "metavars": [
+        "DEBUGGER"
+      ],
+      "defect_class": "safety",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/typescript/debugger.yml"
+    },
+    {
+      "id": "deep-nesting",
+      "name": "Deep Nesting",
+      "severity": "warning",
+      "language": "typescript",
+      "message": "Deep nesting (3+ levels) — consider early returns or extract functions",
+      "query": "  [\n    ;; Pattern 1: if inside if inside if\n    (statement_block\n      (if_statement\n        consequence: (statement_block\n          (if_statement\n            consequence: (statement_block\n              (if_statement) @IF_NESTED)))))\n\n    ;; Pattern 2: for inside if inside if\n    (statement_block\n      (if_statement\n        consequence: (statement_block\n          (if_statement\n            consequence: (statement_block\n              (for_statement) @FOR_NESTED)))))\n\n    ;; Pattern 3: while inside if inside if\n    (statement_block\n      (if_statement\n        consequence: (statement_block\n          (if_statement\n            consequence: (statement_block\n              (while_statement) @WHILE_NESTED)))))\n\n    ;; Pattern 4: try inside if inside if\n    (statement_block\n      (if_statement\n        consequence: (statement_block\n          (if_statement\n            consequence: (statement_block\n              (try_statement) @TRY_NESTED)))))\n\n    ;; Pattern 5: if inside for inside if\n    (statement_block\n      (if_statement\n        consequence: (statement_block\n          (for_statement\n            body: (statement_block\n              (if_statement) @IF_IN_FOR)))))\n\n    ;; Pattern 6: if inside while inside if\n    (statement_block\n      (if_statement\n        consequence: (statement_block\n          (while_statement\n            body: (statement_block\n              (if_statement) @IF_IN_WHILE)))))\n\n    ;; Pattern 7: for inside for inside for\n    (statement_block\n      (for_statement\n        body: (statement_block\n          (for_statement\n            body: (statement_block\n              (for_statement) @FOR_NESTED)))))\n  ]",
+      "metavars": [
+        "IF_NESTED",
+        "FOR_NESTED",
+        "WHILE_NESTED",
+        "TRY_NESTED",
+        "IF_IN_FOR",
+        "IF_IN_WHILE"
+      ],
+      "defect_class": "safety",
+      "inline_tier": "review",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/typescript/deep-nesting.yml"
+    },
+    {
+      "id": "deep-promise-chain",
+      "name": "Deep Promise Chain (4+ levels)",
+      "severity": "warning",
+      "language": "typescript",
+      "message": "Promise chain {{M1}} → {{M2}} → {{M3}} → {{M4}} — consider async/await",
+      "query": "  (call_expression\n    function: (member_expression\n      object: (call_expression\n        function: (member_expression\n          object: (call_expression\n            function: (member_expression\n              object: (call_expression\n                function: (member_expression\n                  property: (property_identifier) @M1)\n                arguments: (arguments))\n              property: (property_identifier) @M2)\n            arguments: (arguments))\n          property: (property_identifier) @M3)\n        arguments: (arguments))\n      property: (property_identifier) @M4)\n    arguments: (arguments)\n    (#match? @M1 \"^(then|catch|finally)$\")\n    (#match? @M2 \"^(then|catch|finally)$\")\n    (#match? @M3 \"^(then|catch|finally)$\")\n    (#match? @M4 \"^(then|catch|finally)$\"))",
+      "metavars": [
+        "M1",
+        "M2",
+        "M3",
+        "M4"
+      ],
+      "defect_class": "async-misuse",
+      "inline_tier": "warning",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/typescript/deep-promise-chain.yml"
+    },
+    {
+      "id": "default-not-last",
+      "name": "Default Clauses Should Be Last",
+      "severity": "error",
+      "language": "typescript",
+      "message": "default clause should be the last case",
+      "query": "  (switch_statement\n    body: (switch_body\n      (switch_default) @DEFAULT\n      (switch_case) @AFTER_CASE))",
+      "metavars": [
+        "DEFAULT",
+        "AFTER_CASE"
+      ],
+      "defect_class": "correctness",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/typescript/default-not-last.yml"
+    },
+    {
+      "id": "duplicate-function-arg",
+      "name": "Function Argument Names Should Be Unique",
+      "severity": "error",
+      "language": "typescript",
+      "message": "Duplicate parameter name '{{NAME}}'",
+      "query": "  (function_declaration\n    parameters: (formal_parameters\n      (identifier) @PARAM1\n      (identifier) @PARAM2))\n  (arrow_function\n    parameters: (formal_parameters\n      (identifier) @PARAM1\n      (identifier) @PARAM2))",
+      "metavars": [
+        "PARAM1",
+        "PARAM2"
+      ],
+      "post_filter": "same_param_name",
+      "defect_class": "correctness",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/typescript/duplicate-function-arg.yml"
+    },
+    {
+      "id": "empty-switch-case",
+      "name": "Switch Cases Should Not Be Empty",
+      "severity": "error",
+      "language": "typescript",
+      "message": "Switch case should not be empty",
+      "query": "  (switch_statement\n    body: (switch_body\n      (switch_case\n        consequence: (statement_block) @BLOCK)))",
+      "metavars": [
+        "BLOCK"
+      ],
+      "post_filter": "is_empty_block",
+      "defect_class": "correctness",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/typescript/empty-switch-case.yml"
+    },
+    {
+      "id": "no-eval",
+      "name": "Eval Usage",
+      "severity": "error",
+      "language": "typescript",
+      "message": "eval() detected — security risk, never use eval",
+      "query": "  (call_expression\n    function: (identifier) @FUNC\n    (#eq? @FUNC \"eval\")\n    arguments: (arguments) @ARGS)",
+      "metavars": [
+        "FUNC",
+        "ARGS"
+      ],
+      "defect_class": "injection",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/typescript/eval.yml"
+    },
+    {
+      "id": "ts-incomplete-assertion",
+      "name": "Incomplete Test Assertion",
+      "severity": "error",
+      "language": "typescript",
+      "message": "Incomplete assertion — expect() chain is not called",
+      "query": "  (call_expression\n    function: (identifier) @EXPECT\n    (#eq? @EXPECT \"expect\")\n    arguments: (arguments)) @EXPR",
+      "metavars": [
+        "EXPECT",
+        "EXPR"
+      ],
+      "post_filter": "incomplete_assertion",
+      "defect_class": "correctness",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/typescript/incomplete-assertion.yml"
+    },
+    {
+      "id": "infinite-loop",
+      "name": "Loops Should Not Be Infinite",
+      "severity": "error",
+      "language": "typescript",
+      "message": "Loop appears to be infinite with no termination condition",
+      "query": "  (while_statement\n    condition: (true)\n    body: (statement_block) @BODY)\n  (for_statement\n    condition: (null)\n    body: (statement_block) @BODY)",
+      "metavars": [
+        "BODY"
+      ],
+      "post_filter": "no_break_or_return_in_body",
+      "defect_class": "correctness",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/typescript/infinite-loop.yml"
+    },
+    {
+      "id": "mixed-async-styles",
+      "name": "Mixed Async/Await and Promise Chains",
+      "severity": "warning",
+      "language": "typescript",
+      "message": "Mixed async/await + promise chains — use consistent async style",
+      "query": "  (function_declaration\n    (async_modifier)\n    body: (statement_block) @BODY)\n\n# Post-filter: Check if body contains both await and .then()",
+      "metavars": [
+        "BODY"
+      ],
+      "post_filter": "has_mixed_async",
+      "defect_class": "async-misuse",
+      "inline_tier": "warning",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/typescript/mixed-async-styles.yml"
+    },
+    {
+      "id": "no-console-in-tests",
+      "name": "Console Statement in Test",
+      "severity": "warning",
+      "language": "typescript",
+      "message": "console.{{METHOD}} in test block — use proper assertions or logging",
+      "query": "  (call_expression\n    function: (member_expression\n      object: (identifier) @OBJ (#eq? @OBJ \"console\")\n      property: (property_identifier) @METHOD)\n    arguments: (arguments) @ARGS)",
+      "metavars": [
+        "OBJ",
+        "METHOD",
+        "ARGS"
+      ],
+      "post_filter": "in_test_block",
+      "defect_class": "safety",
+      "inline_tier": "warning",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/typescript/no-console-in-tests.yml"
+    },
+    {
+      "id": "self-assignment",
+      "name": "Variables Should Not Be Self-Assigned",
+      "severity": "error",
+      "language": "typescript",
+      "message": "'{{VAR}}' is assigned to itself",
+      "query": "  (assignment_expression\n    left: (identifier) @VAR\n    right: (identifier) @SAME\n    (#eq? @VAR @SAME))",
+      "metavars": [
+        "VAR",
+        "SAME"
+      ],
+      "defect_class": "correctness",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/typescript/self-assignment.yml"
+    },
+    {
+      "id": "sql-injection",
+      "name": "SQL Injection Risk",
+      "severity": "error",
+      "language": "typescript",
+      "message": "SQL injection risk — use parameterized queries, never interpolate into SQL",
+      "query": "  (call_expression\n    function: [\n      (identifier) @SQL_FUNC\n      (member_expression property: (property_identifier) @SQL_FUNC)\n    ]\n    arguments: (arguments\n      (template_string (template_substitution) @INTERPOLATION))\n    (#match? @SQL_FUNC \"^(query|execute|exec|run)$\"))",
+      "metavars": [
+        "SQL_FUNC",
+        "INTERPOLATION"
+      ],
+      "defect_class": "injection",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/typescript/sql-injection.yml"
+    },
+    {
+      "id": "switch-case-termination",
+      "name": "Switch Cases Should End With Terminating Statement",
+      "severity": "error",
+      "language": "typescript",
+      "message": "Switch case should end with break, return, throw, or continue",
+      "query": "  (switch_statement\n    body: (switch_body\n      (switch_case\n        consequence: (statement_block\n          (expression_statement) @LAST))\n      (switch_case) @NEXT))",
+      "metavars": [
+        "LAST",
+        "NEXT"
+      ],
+      "post_filter": "no_terminating_statement",
+      "defect_class": "correctness",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/typescript/switch-case-termination.yml"
+    },
+    {
+      "id": "switch-non-case-labels-ts",
+      "name": "Switch Should Not Contain Non-Case Labels",
+      "severity": "error",
+      "language": "typescript",
+      "message": "switch statements should not contain non-case labels",
+      "query": "  (switch_statement\n    body: (switch_body\n      (switch_case\n        (labeled_statement\n          (statement_identifier) @LABEL) @LABELED)))",
+      "metavars": [
+        "LABEL",
+        "LABELED"
+      ],
+      "defect_class": "correctness",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/typescript/switch-non-case-labels.yml"
+    },
+    {
+      "id": "ts-command-injection",
+      "name": "Command Injection Sink",
+      "severity": "error",
+      "language": "typescript",
+      "message": "Potential command injection sink — avoid child_process command execution with untrusted input",
+      "query": "  [\n    (call_expression\n      function: (member_expression\n        object: (identifier) @MOD\n        property: (property_identifier) @FN)\n      arguments: (arguments) @ARGS\n      (#eq? @MOD \"child_process\")\n      (#match? @FN \"^(exec|execSync)$\"))\n    (call_expression\n      function: (member_expression\n        object: (member_expression\n          object: (identifier) @MOD\n          property: (property_identifier) @NS)\n        property: (property_identifier) @FN)\n      arguments: (arguments) @ARGS\n      (#eq? @MOD \"child_process\")\n      (#match? @FN \"^(exec|execSync)$\"))\n  ]",
+      "metavars": [
+        "MOD",
+        "NS",
+        "FN",
+        "ARGS"
+      ],
+      "post_filter": "ts_command_injection_sink",
+      "defect_class": "injection",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/typescript/ts-command-injection.yml"
+    },
+    {
+      "id": "ts-detached-async-call",
+      "name": "Detached Async Call",
+      "severity": "warning",
+      "language": "typescript",
+      "message": "Detached async call — ensure this Promise is awaited or explicitly handled",
+      "query": "  (expression_statement\n    (call_expression\n      function: [\n        (identifier) @FN\n        (member_expression\n          property: (property_identifier) @FN)\n      ]\n      arguments: (arguments) @ARGS)\n    (#match? @FN \"(Async$|fetch$|request$)\"))",
+      "metavars": [
+        "FN",
+        "ARGS"
+      ],
+      "post_filter": "ts_detached_async_call",
+      "defect_class": "async-misuse",
+      "inline_tier": "warning",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/typescript/ts-detached-async-call.yml"
+    },
+    {
+      "id": "ts-dynamic-require",
+      "name": "Dynamic Require Injection",
+      "severity": "error",
+      "language": "typescript",
+      "message": "Dynamic require() — non-literal argument allows loading arbitrary modules",
+      "query": "  (call_expression\n    function: (identifier) @FN\n    arguments: (arguments [(identifier) (member_expression) (call_expression) (await_expression)] @ARG)\n    (#eq? @FN \"require\"))",
+      "metavars": [
+        "FN",
+        "ARG"
+      ],
+      "defect_class": "injection",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/typescript/ts-dynamic-require.yml"
+    },
+    {
+      "id": "ts-hallucinated-react-import",
+      "name": "Hallucinated React Import",
+      "severity": "error",
+      "language": "typescript",
+      "message": "'{NAME}' is a Next.js API, not from 'react' — import from 'next/{CORRECT}' instead",
+      "query": "  (import_statement\n    (import_clause\n      (named_imports\n        (import_specifier\n          name: (identifier) @NAME)))\n    source: (string) @SRC)\n  (#match? @SRC \"^['\\\"]react['\\\"]$\")\n  (#match? @NAME \"^(useRouter|usePathname|useSearchParams|useParams|Link|Image|Script|Head|getServerSideProps|getStaticProps|getStaticPaths|NextPage|NextApiRequest|NextApiResponse|GetServerSideProps|GetStaticProps|GetStaticPaths|notFound|redirect|permanentRedirect)$\")",
+      "metavars": [
+        "NAME",
+        "SRC"
+      ],
+      "post_filter": "match_captures",
+      "post_filter_params": {
+        "SRC": "^['\\\"]react['\\\"]$",
+        "NAME": "^(useRouter|usePathname|useSearchParams|useParams|Link|Image|Script|Head|getServerSideProps|getStaticProps|getStaticPaths|NextPage|NextApiRequest|NextApiResponse|GetServerSideProps|GetStaticProps|GetStaticPaths|notFound|redirect|permanentRedirect)$"
+      },
+      "defect_class": "hallucination",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/typescript/ts-hallucinated-react-import.yml"
+    },
+    {
+      "id": "ts-insecure-random",
+      "name": "Insecure Randomness",
+      "severity": "warning",
+      "language": "typescript",
+      "message": "Insecure randomness source detected — use crypto.getRandomValues or secure RNG APIs",
+      "query": "  (variable_declarator\n    name: (identifier) @VAR\n    value: (call_expression\n      function: (member_expression\n        object: (identifier) @OBJ\n        property: (property_identifier) @FN)\n      arguments: (arguments) @ARGS)\n    (#eq? @OBJ \"Math\")\n    (#eq? @FN \"random\")\n    (#match? @VAR \"(?i)(token|secret|password|key|nonce|salt|csrf|auth|session|credential|hash|otp|pin)\"))",
+      "metavars": [
+        "OBJ",
+        "FN",
+        "ARGS",
+        "VAR"
+      ],
+      "post_filter": "ts_insecure_random_source",
+      "defect_class": "injection",
+      "inline_tier": "warning",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/typescript/ts-insecure-random.yml"
+    },
+    {
+      "id": "ts-nosql-injection",
+      "name": "NoSQL Injection",
+      "severity": "error",
+      "language": "typescript",
+      "message": "NoSQL injection — $where executes JavaScript server-side and must never be used with user input",
+      "query": "  (pair\n    key: [(property_identifier) (string)] @KEY\n    (#match? @KEY \"\\\\$where\"))",
+      "metavars": [
+        "KEY"
+      ],
+      "defect_class": "injection",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/typescript/ts-nosql-injection.yml"
+    },
+    {
+      "id": "ts-open-redirect",
+      "name": "Open Redirect",
+      "severity": "error",
+      "language": "typescript",
+      "message": "Open redirect — unvalidated URL in redirect/location lets attackers send users to malicious sites",
+      "query": "  [\n    (call_expression\n      function: (member_expression\n        object: (identifier) @OBJ\n        property: (property_identifier) @FN)\n      arguments: (arguments (identifier) @URL)\n      (#match? @OBJ \"^(res|response|ctx|context)$\")\n      (#eq? @FN \"redirect\"))\n    (call_expression\n      function: (member_expression\n        object: (identifier) @OBJ\n        property: (property_identifier) @FN)\n      arguments: (arguments (member_expression) @URL)\n      (#match? @OBJ \"^(res|response|ctx|context)$\")\n      (#eq? @FN \"redirect\"))\n    (call_expression\n      function: (member_expression\n        object: (identifier) @OBJ\n        property: (property_identifier) @FN)\n      arguments: (arguments (call_expression) @URL)\n      (#match? @OBJ \"^(res|response|ctx|context)$\")\n      (#eq? @FN \"redirect\"))\n  ]\n  [\n    (assignment_expression\n      left: (member_expression\n        object: (member_expression\n          object: (identifier) @WIN\n          property: (property_identifier) @LOC)\n        property: (property_identifier) @PROP)\n      right: (identifier) @VALUE\n      (#eq? @WIN \"window\")\n      (#eq? @LOC \"location\")\n      (#eq? @PROP \"href\"))\n    (assignment_expression\n      left: (member_expression\n        object: (member_expression\n          object: (identifier) @WIN\n          property: (property_identifier) @LOC)\n        property: (property_identifier) @PROP)\n      right: (member_expression) @VALUE\n      (#eq? @WIN \"window\")\n      (#eq? @LOC \"location\")\n      (#eq? @PROP \"href\"))\n    (assignment_expression\n      left: (member_expression\n        object: (member_expression\n          object: (identifier) @WIN\n          property: (property_identifier) @LOC)\n        property: (property_identifier) @PROP)\n      right: (call_expression) @VALUE\n      (#eq? @WIN \"window\")\n      (#eq? @LOC \"location\")\n      (#eq? @PROP \"href\"))\n  ]",
+      "metavars": [
+        "OBJ",
+        "FN",
+        "URL",
+        "WIN",
+        "LOC",
+        "PROP",
+        "VALUE"
+      ],
+      "defect_class": "injection",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/typescript/ts-open-redirect.yml"
+    },
+    {
+      "id": "ts-react-antipatterns",
+      "name": "React Anti-Pattern",
+      "severity": "warning",
+      "language": "typescript",
+      "message": "React anti-pattern: setState inside a loop causes multiple re-renders — batch with a single state update",
+      "query": "  [\n    (for_statement\n      (statement_block) @BODY\n      (#match? @BODY \"set[A-Z]\")\n      (#not-match? @BODY \"set(Timeout|Interval|Immediate)\"))\n    (for_in_statement\n      (statement_block) @BODY\n      (#match? @BODY \"set[A-Z]\")\n      (#not-match? @BODY \"set(Timeout|Interval|Immediate)\"))\n    (while_statement\n      (statement_block) @BODY\n      (#match? @BODY \"set[A-Z]\")\n      (#not-match? @BODY \"set(Timeout|Interval|Immediate)\"))\n  ]",
+      "metavars": [
+        "BODY"
+      ],
+      "defect_class": "logic-error",
+      "inline_tier": "warning",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/typescript/ts-react-antipatterns.yml"
+    },
+    {
+      "id": "ts-ssrf",
+      "name": "SSRF Risk",
+      "severity": "error",
+      "language": "typescript",
+      "message": "Potential SSRF sink — validate and allowlist outbound URLs",
+      "query": "  [\n    (call_expression\n      function: (identifier) @FN\n      arguments: (arguments [(identifier) (member_expression) (call_expression) (await_expression)] @URL)\n      (#match? @FN \"^(fetch|get|post|put|patch|delete|request)$\"))\n    (call_expression\n      function: (member_expression\n        object: (identifier) @OBJ\n        property: (property_identifier) @FN)\n      arguments: (arguments [(identifier) (member_expression) (call_expression) (await_expression)] @URL)\n      (#match? @FN \"^(fetch|get|post|put|patch|delete|request)$\"))\n  ]",
+      "metavars": [
+        "OBJ",
+        "FN",
+        "URL"
+      ],
+      "post_filter": "ts_ssrf_sink",
+      "defect_class": "injection",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/typescript/ts-ssrf.yml"
+    },
+    {
+      "id": "ts-weak-hash",
+      "name": "Weak Hash Primitive",
+      "severity": "error",
+      "language": "typescript",
+      "message": "Weak hash primitive selected (md5/sha1) — use sha256+ for security-sensitive contexts",
+      "query": "  (call_expression\n    function: (member_expression\n      property: (property_identifier) @FN)\n    arguments: (arguments\n      (string (string_fragment) @ALG)\n      (_)*)\n    (#eq? @FN \"createHash\")\n    (#match? @ALG \"^(md5|sha1)$\"))",
+      "metavars": [
+        "FN",
+        "ALG"
+      ],
+      "post_filter": "ts_weak_hash_algorithm",
+      "defect_class": "injection",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/typescript/ts-weak-hash.yml"
+    },
+    {
+      "id": "ts-xss-dom-sink",
+      "name": "XSS DOM Sink",
+      "severity": "error",
+      "language": "typescript",
+      "message": "XSS risk — dynamic value written to innerHTML/outerHTML or document.write()",
+      "query": "  [\n    (assignment_expression\n      left: (member_expression\n        property: (property_identifier) @PROP)\n      right: (identifier) @VALUE\n      (#match? @PROP \"^(innerHTML|outerHTML)$\"))\n    (assignment_expression\n      left: (member_expression\n        property: (property_identifier) @PROP)\n      right: (member_expression) @VALUE\n      (#match? @PROP \"^(innerHTML|outerHTML)$\"))\n    (assignment_expression\n      left: (member_expression\n        property: (property_identifier) @PROP)\n      right: (call_expression) @VALUE\n      (#match? @PROP \"^(innerHTML|outerHTML)$\"))\n    (assignment_expression\n      left: (member_expression\n        property: (property_identifier) @PROP)\n      right: (await_expression) @VALUE\n      (#match? @PROP \"^(innerHTML|outerHTML)$\"))\n  ]\n  [\n    (call_expression\n      function: (member_expression\n        object: (identifier) @OBJ\n        property: (property_identifier) @FN)\n      arguments: (arguments (identifier) @ARG)\n      (#eq? @OBJ \"document\")\n      (#match? @FN \"^(write|writeln)$\"))\n    (call_expression\n      function: (member_expression\n        object: (identifier) @OBJ\n        property: (property_identifier) @FN)\n      arguments: (arguments (member_expression) @ARG)\n      (#eq? @OBJ \"document\")\n      (#match? @FN \"^(write|writeln)$\"))\n    (call_expression\n      function: (member_expression\n        object: (identifier) @OBJ\n        property: (property_identifier) @FN)\n      arguments: (arguments (call_expression) @ARG)\n      (#eq? @OBJ \"document\")\n      (#match? @FN \"^(write|writeln)$\"))\n  ]",
+      "metavars": [
+        "PROP",
+        "VALUE",
+        "OBJ",
+        "FN",
+        "ARG"
+      ],
+      "defect_class": "injection",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/typescript/ts-xss-dom-sink.yml"
+    },
+    {
+      "id": "unsafe-regex",
+      "name": "Dynamic Regex Construction",
+      "severity": "error",
+      "language": "typescript",
+      "message": "Dynamic regex from user input — can cause ReDoS (Regular Expression Denial of Service)",
+      "query": "  (new_expression\n    constructor: (identifier) @CTOR\n    (#eq? @CTOR \"RegExp\")\n    arguments: (arguments\n      (template_string\n        (template_substitution) @INTERPOLATION) @PATTERN)\n    (#not-match? @INTERPOLATION \"escape|Escape|replace\"))",
+      "metavars": [
+        "CTOR",
+        "INTERPOLATION",
+        "PATTERN"
+      ],
+      "defect_class": "injection",
+      "inline_tier": "blocking",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/typescript/unsafe-regex.yml"
+    },
+    {
+      "id": "variable-shadowing",
+      "name": "Variable Shadowing",
+      "severity": "warning",
+      "language": "typescript",
+      "message": "Variable '{{NAME}}' shadows a parameter — use a distinct name",
+      "query": "  (function_declaration\n    parameters: (formal_parameters\n      (required_parameter\n        pattern: (identifier) @PARAM))\n    body: (statement_block\n      (lexical_declaration\n        (variable_declarator\n          name: (identifier) @NAME))))",
+      "metavars": [
+        "PARAM",
+        "NAME"
+      ],
+      "post_filter": "name_matches_param",
+      "defect_class": "safety",
+      "inline_tier": "review",
+      "filePath": "/home/alex/.npm-global/lib/node_modules/pi-lens/rules/tree-sitter-queries/typescript/variable-shadowing.yml"
+    }
+  ]
+}

apps/web/src/api/config_folders.test.ts

@@ -1,131 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-
-import {
-  createConfigFolder,
-  deleteConfigFolder,
-  listConfigFolders,
-  updateConfigFolder,
-} from "../api/config_folders";
-
-const mockGet = vi.fn();
-const mockPost = vi.fn();
-const mockPut = vi.fn();
-const mockDelete = vi.fn();
-
-vi.mock("../api/client", () => ({
-  apiClient: {
-    get: (...args: unknown[]) => mockGet(...args),
-    post: (...args: unknown[]) => mockPost(...args),
-    put: (...args: unknown[]) => mockPut(...args),
-    delete: (...args: unknown[]) => mockDelete(...args),
-    interceptors: {
-      response: {
-        use: vi.fn(),
-      },
-    },
-  },
-  shouldSkipAuthRedirect: vi.fn(() => false),
-}));
-
-describe("config_folders API", () => {
-  describe("listConfigFolders", () => {
-    it("returns folders with files and overrides", async () => {
-      const mockResponse = {
-        data: [
-          {
-            id: "folder-1",
-            name: "my-dotfiles",
-            description: "My personal config files",
-            mount_path: "/home/user",
-            files: { ".zshrc": "export ZSH=\"$HOME/.oh-my-zsh\"" },
-            project_overrides: {},
-            is_active: true,
-            user_id: "user-1",
-            created_at: "2024-01-01T00:00:00Z",
-            updated_at: "2024-01-01T00:00:00Z",
-          },
-        ],
-      };
-      mockGet.mockResolvedValue(mockResponse);
-
-      const result = await listConfigFolders();
-
-      expect(result[0].name).toBe("my-dotfiles");
-      expect(result[0].files).toEqual({ ".zshrc": "export ZSH=\"$HOME/.oh-my-zsh\"" });
-      expect(mockGet).toHaveBeenCalledWith("/config-folders");
-    });
-  });
-
-  describe("createConfigFolder", () => {
-    it("creates folder with files", async () => {
-      const mockResponse = {
-        data: {
-          id: "folder-new",
-          name: "new-folder",
-          mount_path: "/workspace",
-          files: { ".env": "API_URL=http://localhost" },
-          is_active: true,
-          user_id: "user-1",
-          created_at: "2024-01-01T00:00:00Z",
-          updated_at: "2024-01-01T00:00:00Z",
-        },
-      };
-      mockPost.mockResolvedValue(mockResponse);
-
-      const result = await createConfigFolder({
-        name: "new-folder",
-        mount_path: "/workspace",
-        files: { ".env": "API_URL=http://localhost" },
-      });
-
-      expect(result.name).toBe("new-folder");
-      expect(mockPost).toHaveBeenCalledWith(
-        "/config-folders",
-        expect.objectContaining({
-          name: "new-folder",
-          mount_path: "/workspace",
-        })
-      );
-    });
-  });
-
-  describe("updateConfigFolder", () => {
-    it("updates folder files", async () => {
-      const mockResponse = {
-        data: {
-          id: "folder-1",
-          name: "updated-folder",
-          mount_path: "/home/user",
-          files: { ".bashrc": "alias ll='ls -la'" },
-          is_active: true,
-          user_id: "user-1",
-          created_at: "2024-01-01T00:00:00Z",
-          updated_at: "2024-01-01T00:00:00Z",
-        },
-      };
-      mockPut.mockResolvedValue(mockResponse);
-
-      const result = await updateConfigFolder("folder-1", {
-        files: { ".bashrc": "alias ll='ls -la'" },
-      });
-
-      expect(result.files).toEqual({ ".bashrc": "alias ll='ls -la'" });
-      expect(mockPut).toHaveBeenCalledWith(
-        "/config-folders/folder-1",
-        expect.objectContaining({
-          files: { ".bashrc": "alias ll='ls -la'" },
-        })
-      );
-    });
-  });
-
-  describe("deleteConfigFolder", () => {
-    it("deletes folder", async () => {
-      mockDelete.mockResolvedValue({ data: undefined });
-
-      await deleteConfigFolder("folder-1");
-
-      expect(mockDelete).toHaveBeenCalledWith("/config-folders/folder-1");
-    });
-  });
-});

apps/web/src/api/config_folders.ts

@@ -1,95 +0,0 @@
-import { apiClient } from "./client";
-
-export interface ConfigFolder {
-  id: string;
-  user_id: string;
-  name: string;
-  description: string | null;
-  mount_path: string;
-  files: Record<string, string>;
-  project_overrides: Record<string, { mount_path?: string; files?: Record<string, string> }> | null;
-  is_active: boolean;
-  created_at: string;
-  updated_at: string;
-}
-
-export interface CreateConfigFolderRequest {
-  name: string;
-  description?: string;
-  mount_path: string;
-  files?: Record<string, string>;
-  is_active?: boolean;
-}
-
-export interface UpdateConfigFolderRequest {
-  name?: string;
-  description?: string;
-  mount_path?: string;
-  files?: Record<string, string>;
-  is_active?: boolean;
-}
-
-export interface ProjectOverrideRequest {
-  mount_path?: string;
-  files?: Record<string, string>;
-}
-
-export const listConfigFolders = async (): Promise<ConfigFolder[]> => {
-  const response = await apiClient.get<ConfigFolder[]>("/config-folders");
-  return response.data;
-};
-
-export const getConfigFolder = async (id: string): Promise<ConfigFolder> => {
-  const response = await apiClient.get<ConfigFolder>(`/config-folders/${id}`);
-  return response.data;
-};
-
-export const createConfigFolder = async (
-  data: CreateConfigFolderRequest
-): Promise<ConfigFolder> => {
-  const response = await apiClient.post<ConfigFolder>("/config-folders", data);
-  return response.data;
-};
-
-export const updateConfigFolder = async (
-  id: string,
-  data: UpdateConfigFolderRequest
-): Promise<ConfigFolder> => {
-  const response = await apiClient.put<ConfigFolder>(`/config-folders/${id}`, data);
-  return response.data;
-};
-
-export const deleteConfigFolder = async (id: string): Promise<void> => {
-  await apiClient.delete(`/config-folders/${id}`);
-};
-
-export const addProjectOverride = async (
-  id: string,
-  projectId: string,
-  data: ProjectOverrideRequest
-): Promise<ConfigFolder> => {
-  const response = await apiClient.post<ConfigFolder>(
-    `/config-folders/${id}/overrides/${projectId}`,
-    data
-  );
-  return response.data;
-};
-
-export const updateProjectOverride = async (
-  id: string,
-  projectId: string,
-  data: ProjectOverrideRequest
-): Promise<ConfigFolder> => {
-  const response = await apiClient.put<ConfigFolder>(
-    `/config-folders/${id}/overrides/${projectId}`,
-    data
-  );
-  return response.data;
-};
-
-export const deleteProjectOverride = async (
-  id: string,
-  projectId: string
-): Promise<void> => {
-  await apiClient.delete(`/config-folders/${id}/overrides/${projectId}`);
-};

apps/web/src/api/config_profiles.ts

@@ -1,156 +1,169 @@
 import { apiClient } from "./client";
 
 export interface ConfigProfile {
-  id: string;
-  user_id: string;
-  name: string;
-  description: string | null;
-  project_id: string | null;
-  tool_type_id: string | null;
-  env_vars: Record<string, string>;
-  runtime_hints: Record<string, unknown>;
-  mounts: ConfigProfileMount[];
-  git_mounts: GitMount[];
-  files: Record<string, string>;
-  is_default: boolean;
-  includes: ConfigProfileInclude[];
-  created_at: string;
-  updated_at: string;
+	id: string;
+	user_id: string;
+	name: string;
+	description: string | null;
+	project_id: string | null;
+	tool_type_id: string | null;
+	env_vars: Record<string, string>;
+	runtime_hints: Record<string, unknown>;
+	mounts: ConfigProfileMount[];
+	git_mounts: GitMount[];
+	files: Record<string, string>;
+	is_default: boolean;
+	includes: ConfigProfileInclude[];
+	created_at: string;
+	updated_at: string;
 }
 
 export interface ConfigProfileMount {
-  target: string;
-  mode: "ro" | "rw";
-  files: Record<string, string>;
+	target: string;
+	mode: "ro" | "rw";
+	files: Record<string, string>;
+}
+
+export interface GitMountMapping {
+	source_path: string;
+	target_path: string;
 }
 
 export interface GitMount {
-  remote_url: string;
-  source_path: string;
-  target_path: string;
-  branch?: string;
+	remote_url: string;
+	branch?: string;
+	mappings: GitMountMapping[];
+	// Legacy fields (for backward compatibility when reading old data)
+	source_path?: string;
+	target_path?: string;
 }
 
 export interface ConfigProfileInclude {
-  id: string;
-  included_profile_id: string;
-  order_index: number;
+	id: string;
+	included_profile_id: string;
+	order_index: number;
 }
 
 export interface ResolvedProfile {
-  profile_id: string;
-  profile_name: string;
-  env_vars: Record<string, string>;
-  runtime_hints: Record<string, unknown>;
-  mounts: ResolvedMount[];
-  git_mounts: GitMount[];
-  files: Record<string, string>;
-  overrides: {
-    env_vars: Record<string, string>;
-    runtime_hints: Record<string, string>;
-    files: Record<string, string>;
-    mounts: Record<string, string>;
-  };
-  included_profiles: Array<{ id: string; name: string }>;
+	profile_id: string;
+	profile_name: string;
+	env_vars: Record<string, string>;
+	runtime_hints: Record<string, unknown>;
+	mounts: ResolvedMount[];
+	git_mounts: GitMount[];
+	files: Record<string, string>;
+	overrides: {
+		env_vars: Record<string, string>;
+		runtime_hints: Record<string, string>;
+		files: Record<string, string>;
+		mounts: Record<string, string>;
+	};
+	included_profiles: Array<{ id: string; name: string }>;
 }
 
 export interface ResolvedMount {
-  target: string;
-  mode: "ro" | "rw";
-  files: Record<string, string>;
-  overridden_files: Record<string, string>;
+	target: string;
+	mode: "ro" | "rw";
+	files: Record<string, string>;
+	overridden_files: Record<string, string>;
 }
 
 export interface CreateConfigProfileRequest {
-  name: string;
-  description?: string;
-  project_id?: string;
-  tool_type_id?: string;
-  env_vars?: Record<string, string>;
-  runtime_hints?: Record<string, unknown>;
-  mounts?: ConfigProfileMount[];
-  git_mounts?: GitMount[];
-  files?: Record<string, string>;
-  is_default?: boolean;
+	name: string;
+	description?: string;
+	project_id?: string;
+	tool_type_id?: string;
+	env_vars?: Record<string, string>;
+	runtime_hints?: Record<string, unknown>;
+	mounts?: ConfigProfileMount[];
+	git_mounts?: GitMount[];
+	files?: Record<string, string>;
+	is_default?: boolean;
 }
 
 export interface UpdateConfigProfileRequest {
-  name?: string;
-  description?: string;
-  project_id?: string;
-  tool_type_id?: string;
-  env_vars?: Record<string, string>;
-  runtime_hints?: Record<string, unknown>;
-  mounts?: ConfigProfileMount[];
-  git_mounts?: GitMount[];
-  files?: Record<string, string>;
-  is_default?: boolean;
+	name?: string;
+	description?: string;
+	project_id?: string;
+	tool_type_id?: string;
+	env_vars?: Record<string, string>;
+	runtime_hints?: Record<string, unknown>;
+	mounts?: ConfigProfileMount[];
+	git_mounts?: GitMount[];
+	files?: Record<string, string>;
+	is_default?: boolean;
 }
 
 export interface UpdateIncludesRequest {
-  includes: string[];
+	includes: string[];
 }
 
 export const listConfigProfiles = async (
-  projectId?: string,
-  toolTypeId?: string
+	projectId?: string,
+	toolTypeId?: string,
 ): Promise<ConfigProfile[]> => {
-  const response = await apiClient.get<ConfigProfile[]>("/config-profiles", {
-    params: { project_id: projectId, tool_type_id: toolTypeId },
-  });
-  return response.data;
+	const response = await apiClient.get<ConfigProfile[]>("/config-profiles", {
+		params: { project_id: projectId, tool_type_id: toolTypeId },
+	});
+	return response.data;
 };
 
 export const getConfigProfile = async (id: string): Promise<ConfigProfile> => {
-  const response = await apiClient.get<ConfigProfile>(`/config-profiles/${id}`);
-  return response.data;
+	const response = await apiClient.get<ConfigProfile>(`/config-profiles/${id}`);
+	return response.data;
 };
 
 export const createConfigProfile = async (
-  data: CreateConfigProfileRequest
+	data: CreateConfigProfileRequest,
 ): Promise<ConfigProfile> => {
-  const response = await apiClient.post<ConfigProfile>("/config-profiles", data);
-  return response.data;
+	const response = await apiClient.post<ConfigProfile>(
+		"/config-profiles",
+		data,
+	);
+	return response.data;
 };
 
 export const updateConfigProfile = async (
-  id: string,
-  data: UpdateConfigProfileRequest
+	id: string,
+	data: UpdateConfigProfileRequest,
 ): Promise<ConfigProfile> => {
-  const response = await apiClient.put<ConfigProfile>(`/config-profiles/${id}`, data);
-  return response.data;
+	const response = await apiClient.put<ConfigProfile>(
+		`/config-profiles/${id}`,
+		data,
+	);
+	return response.data;
 };
 
 export const deleteConfigProfile = async (id: string): Promise<void> => {
-  await apiClient.delete(`/config-profiles/${id}`);
+	await apiClient.delete(`/config-profiles/${id}`);
 };
 
 export const updateProfileIncludes = async (
-  id: string,
-  data: UpdateIncludesRequest
+	id: string,
+	data: UpdateIncludesRequest,
 ): Promise<ConfigProfile> => {
-  const response = await apiClient.put<ConfigProfile>(
-    `/config-profiles/${id}/includes`,
-    data
-  );
-  return response.data;
+	const response = await apiClient.put<ConfigProfile>(
+		`/config-profiles/${id}/includes`,
+		data,
+	);
+	return response.data;
 };
 
 export const previewConfigProfile = async (
-  id: string
+	id: string,
 ): Promise<ResolvedProfile> => {
-  const response = await apiClient.get<ResolvedProfile>(
-    `/config-profiles/${id}/preview`
-  );
-  return response.data;
+	const response = await apiClient.get<ResolvedProfile>(
+		`/config-profiles/${id}/preview`,
+	);
+	return response.data;
 };
 
 export const resolveDefaultProfile = async (
-  projectId: string,
-  toolTypeId: string
+	projectId: string,
+	toolTypeId: string,
 ): Promise<{ profile_id: string | null; profile_name: string | null }> => {
-  const response = await apiClient.get("/config-profiles/defaults/resolve", {
-    params: { project_id: projectId, tool_type_id: toolTypeId },
-  });
-  return response.data;
+	const response = await apiClient.get("/config-profiles/defaults/resolve", {
+		params: { project_id: projectId, tool_type_id: toolTypeId },
+	});
+	return response.data;
 };

apps/web/src/api/terminal.ts

@@ -0,0 +1,77 @@
+import { apiClient } from "./client";
+
+export interface TerminalSession {
+	id: string;
+	name: string;
+	status: string;
+	has_websockets: boolean;
+	created_at: string;
+	last_activity_at: string | null;
+}
+
+export interface TerminalSessionListResponse {
+	sessions: TerminalSession[];
+}
+
+export interface TerminalSessionCreateRequest {
+	name?: string;
+}
+
+export interface TerminalSessionCreateResponse {
+	id: string;
+	name: string;
+	status: string;
+	created_at: string;
+}
+
+export async function listTerminalSessions(
+	instanceId: string,
+): Promise<TerminalSession[]> {
+	const response = await apiClient.get(
+		`/instances/${instanceId}/terminal/sessions`,
+	);
+	return response.data.sessions;
+}
+
+export async function createTerminalSession(
+	instanceId: string,
+	name?: string,
+): Promise<TerminalSessionCreateResponse> {
+	const response = await apiClient.post(
+		`/instances/${instanceId}/terminal/sessions`,
+		{ name },
+	);
+	return response.data;
+}
+
+export async function closeTerminalSession(
+	instanceId: string,
+	sessionId: string,
+): Promise<{ status: string; session_id: string }> {
+	const response = await apiClient.delete(
+		`/instances/${instanceId}/terminal/sessions/${sessionId}`,
+	);
+	return response.data;
+}
+
+export async function resetTerminalSession(
+	instanceId: string,
+	sessionId: string,
+): Promise<{ id: string; name: string; status: string }> {
+	const response = await apiClient.post(
+		`/instances/${instanceId}/terminal/sessions/${sessionId}/reset`,
+	);
+	return response.data;
+}
+
+export async function renameTerminalSession(
+	instanceId: string,
+	sessionId: string,
+	name: string,
+): Promise<{ id: string; name: string }> {
+	const response = await apiClient.post(
+		`/instances/${instanceId}/terminal/sessions/${sessionId}/rename`,
+		{ name },
+	);
+	return response.data;
+}

apps/web/src/api/tool_configs.ts

@@ -1,75 +0,0 @@
-import { apiClient } from "./client";
-
-export interface ToolConfig {
-  id: string;
-  tool_type_id: string;
-  project_id: string | null;
-  key: string;
-  value: string;
-  config_type: string;
-  file_path: string | null;
-  port_override: number | null;
-  start_command: string | null;
-  working_directory: string | null;
-  environment_variables: Record<string, string> | null;
-  volumes: Array<{ source: string; target: string; type?: string }> | null;
-}
-
-export interface CreateToolConfigRequest {
-  tool_type_id: string;
-  project_id?: string;
-  key: string;
-  value: string;
-  config_type?: string;
-  file_path?: string;
-  port_override?: number;
-  start_command?: string;
-  working_directory?: string;
-  environment_variables?: Record<string, string>;
-  volumes?: Array<{ source: string; target: string; type?: string }>;
-}
-
-export const listToolConfigs = async (
-  tool_type_id?: string,
-  project_id?: string
-): Promise<ToolConfig[]> => {
-  const params = new URLSearchParams();
-  if (tool_type_id) params.append("tool_type_id", tool_type_id);
-  if (project_id) params.append("project_id", project_id);
-  
-  const response = await apiClient.get<{ configs: ToolConfig[] }>(
-    `/tool-configs?${params.toString()}`
-  );
-  return response.data.configs;
-};
-
-export const createToolConfig = async (
-  data: CreateToolConfigRequest
-): Promise<ToolConfig> => {
-  const response = await apiClient.post<{ configs: ToolConfig[] }>("/tool-configs", data);
-  return response.data.configs[0];
-};
-
-export const updateToolConfig = async (
-  id: string,
-  data: CreateToolConfigRequest
-): Promise<ToolConfig> => {
-  const response = await apiClient.put<{ configs: ToolConfig[] }>(
-    `/tool-configs/${id}`,
-    data
-  );
-  return response.data.configs[0];
-};
-
-export const deleteToolConfig = async (id: string): Promise<void> => {
-  await apiClient.delete(`/tool-configs/${id}`);
-};
-
-export const getToolConfigDefaults = async (
-  toolTypeId: string
-): Promise<ToolConfig> => {
-  const response = await apiClient.get<ToolConfig>(
-    `/tool-configs/defaults/${toolTypeId}`
-  );
-  return response.data;
-};

apps/web/src/components/git-mount-editor.tsx

@@ -1,226 +1,423 @@
-import { useState } from "react";
+import { useState, useEffect } from "react";
 import { Icon } from "./icon";
-import type { GitMount } from "../api/config_profiles";
+import type { GitMount, GitMountMapping } from "../api/config_profiles";
 
 interface GitMountEditorProps {
-  mounts: GitMount[];
-  onChange: (mounts: GitMount[]) => void;
+	mounts: GitMount[];
+	onChange: (mounts: GitMount[]) => void;
+}
+
+function normalizeMount(mount: GitMount): GitMount {
+	// Auto-convert legacy source_path + target_path to mappings
+	if (
+		(!mount.mappings || mount.mappings.length === 0) &&
+		mount.source_path !== undefined &&
+		mount.target_path !== undefined
+	) {
+		return {
+			remote_url: mount.remote_url,
+			branch: mount.branch,
+			mappings: [
+				{
+					source_path: mount.source_path || ".",
+					target_path: mount.target_path,
+				},
+			],
+		};
+	}
+	return mount;
+}
+
+function normalizeMounts(mounts: GitMount[]): GitMount[] {
+	return mounts.map(normalizeMount);
 }
 
 export const GitMountEditor = ({ mounts, onChange }: GitMountEditorProps) => {
-  const [editingIndex, setEditingIndex] = useState<number | null>(null);
-  const [newMount, setNewMount] = useState<GitMount>({
-    remote_url: "",
-    source_path: ".",
-    target_path: "",
-    branch: "",
-  });
+	const [normalizedMounts, setNormalizedMounts] = useState<GitMount[]>(() =>
+		normalizeMounts(mounts),
+	);
+	const [editingIndex, setEditingIndex] = useState<number | null>(null);
+	const [isAdding, setIsAdding] = useState(false);
 
-  const handleAdd = (mount: GitMount) => {
-    onChange([...mounts, mount]);
-    setNewMount({ remote_url: "", source_path: ".", target_path: "", branch: "" });
-  };
+	useEffect(() => {
+		setNormalizedMounts(normalizeMounts(mounts));
+	}, [mounts]);
 
-  const handleUpdate = (index: number, updated: GitMount) => {
-    const updatedMounts = [...mounts];
-    updatedMounts[index] = updated;
-    onChange(updatedMounts);
-    setEditingIndex(null);
-  };
+	const handleAdd = (mount: GitMount) => {
+		const updated = [...normalizedMounts, normalizeMount(mount)];
+		setNormalizedMounts(updated);
+		onChange(updated);
+		setIsAdding(false);
+	};
 
-  const handleRemove = (index: number) => {
-    onChange(mounts.filter((_, i) => i !== index));
-  };
+	const handleUpdate = (index: number, updated: GitMount) => {
+		const updatedMounts = [...normalizedMounts];
+		updatedMounts[index] = normalizeMount(updated);
+		setNormalizedMounts(updatedMounts);
+		onChange(updatedMounts);
+		setEditingIndex(null);
+	};
 
-  const validatePath = (path: string, isTarget: boolean): string | null => {
-    if (!path) return isTarget ? "Target path is required" : null;
-    if (path.includes("..")) return "Path cannot contain ..";
-    if (!isTarget && path.startsWith("/")) return "Source path must be relative";
-    return null;
-  };
+	const handleRemove = (index: number) => {
+		const updated = normalizedMounts.filter((_, i) => i !== index);
+		setNormalizedMounts(updated);
+		onChange(updated);
+	};
 
-  const validateUrl = (url: string): string | null => {
-    if (!url) return "Git URL is required";
-    if (!url.startsWith("http://") && !url.startsWith("https://") && !url.startsWith("git@") && !url.startsWith("ssh://")) {
-      return "Must be a valid git URL (https://, git@, or ssh://)";
-    }
-    return null;
-  };
+	return (
+		<div className="git-mount-editor">
+			<h4 style={{ margin: "0 0 0.75rem 0" }}>Git Mounts</h4>
+			<p
+				className="muted"
+				style={{ margin: "0 0 0.75rem 0", fontSize: "0.875rem" }}
+			>
+				Clone a repository once and mount multiple directories from it.
+			</p>
 
-  return (
-    <div className="git-mount-editor">
-      <h4 className="section-subtitle">Git Mounts</h4>
-      
-      {mounts.length > 0 && (
-        <div className="git-mount-list">
-          {mounts.map((mount, index) => (
-            <div key={index} className="git-mount-item">
-              {editingIndex === index ? (
-                <GitMountForm
-                  mount={mount}
-                  onSave={(updated) => handleUpdate(index, updated)}
-                  onCancel={() => setEditingIndex(null)}
-                  validatePath={validatePath}
-                  validateUrl={validateUrl}
-                />
-              ) : (
-                <div className="git-mount-display">
-                  <div className="git-mount-info">
-                    <span className="git-mount-repo">{mount.remote_url}</span>
-                    <span className="git-mount-paths">
-                      {mount.source_path || "."} → {mount.target_path}
-                    </span>
-                    {mount.branch && (
-                      <span className="git-mount-branch">@{mount.branch}</span>
-                    )}
-                  </div>
-                  <div className="git-mount-actions">
-                    <button
-                      type="button"
-                      className="icon-button"
-                      onClick={() => setEditingIndex(index)}
-                      title="Edit"
-                    >
-                      <Icon name="edit" size="sm" />
-                    </button>
-                    <button
-                      type="button"
-                      className="icon-button danger"
-                      onClick={() => handleRemove(index)}
-                      title="Remove"
-                    >
-                      <Icon name="delete" size="sm" />
-                    </button>
-                  </div>
-                </div>
-              )}
-            </div>
-          ))}
-        </div>
-      )}
+			{normalizedMounts.length > 0 && (
+				<div
+					className="git-mount-list"
+					style={{
+						display: "flex",
+						flexDirection: "column",
+						gap: "0.75rem",
+						marginBottom: "1rem",
+					}}
+				>
+					{normalizedMounts.map((mount, index) => (
+						<div key={index} className="card" style={{ padding: "1rem" }}>
+							{editingIndex === index ? (
+								<GitMountForm
+									mount={mount}
+									onSave={(updated) => handleUpdate(index, updated)}
+									onCancel={() => setEditingIndex(null)}
+								/>
+							) : (
+								<div>
+									<div
+										style={{
+											display: "flex",
+											justifyContent: "space-between",
+											alignItems: "flex-start",
+											marginBottom: "0.5rem",
+										}}
+									>
+										<div style={{ flex: 1, minWidth: 0 }}>
+											<div
+												style={{
+													fontWeight: 600,
+													fontSize: "0.9375rem",
+													marginBottom: "0.25rem",
+												}}
+											>
+												{mount.remote_url}
+												{mount.branch && (
+													<span
+														style={{
+															color: "var(--muted)",
+															fontWeight: 400,
+															marginLeft: "0.5rem",
+														}}
+													>
+														@{mount.branch}
+													</span>
+												)}
+											</div>
+											<div
+												style={{
+													display: "flex",
+													flexDirection: "column",
+													gap: "0.25rem",
+												}}
+											>
+												{mount.mappings?.map((m, mi) => (
+													<div
+														key={mi}
+														style={{
+															fontSize: "0.875rem",
+															color: "var(--muted)",
+															fontFamily: "monospace",
+														}}
+													>
+														{m.source_path || "."} → {m.target_path}
+													</div>
+												))}
+											</div>
+										</div>
+										<div
+											style={{ display: "flex", gap: "0.25rem", flexShrink: 0 }}
+										>
+											<button
+												type="button"
+												className="ghost-button small"
+												onClick={() => setEditingIndex(index)}
+												title="Edit"
+											>
+												<Icon name="edit" size="sm" />
+											</button>
+											<button
+												type="button"
+												className="ghost-button small"
+												onClick={() => handleRemove(index)}
+												title="Remove"
+											>
+												<Icon name="delete" size="sm" />
+											</button>
+										</div>
+									</div>
+								</div>
+							)}
+						</div>
+					))}
+				</div>
+			)}
 
-      <div className="git-mount-add">
-        <h5>Add Git Mount</h5>
-        <GitMountForm
-          mount={newMount}
-          onSave={handleAdd}
-          onCancel={() => setNewMount({ remote_url: "", source_path: ".", target_path: "", branch: "" })}
-          validatePath={validatePath}
-          validateUrl={validateUrl}
-          isNew
-        />
-      </div>
-    </div>
-  );
+			{isAdding ? (
+				<div className="card" style={{ padding: "1rem" }}>
+					<GitMountForm
+						mount={{
+							remote_url: "",
+							branch: "",
+							mappings: [{ source_path: ".", target_path: "" }],
+						}}
+						onSave={handleAdd}
+						onCancel={() => setIsAdding(false)}
+					/>
+				</div>
+			) : (
+				<button
+					type="button"
+					className="secondary-button"
+					onClick={() => setIsAdding(true)}
+				>
+					<Icon name="add" size="sm" />
+					Add Git Mount
+				</button>
+			)}
+		</div>
+	);
 };
 
 interface GitMountFormProps {
-  mount: GitMount;
-  onSave: (mount: GitMount) => void;
-  onCancel: () => void;
-  validatePath: (path: string, isTarget: boolean) => string | null;
-  validateUrl: (url: string) => string | null;
-  isNew?: boolean;
+	mount: GitMount;
+	onSave: (mount: GitMount) => void;
+	onCancel: () => void;
 }
 
-const GitMountForm = ({ mount, onSave, onCancel, validatePath, validateUrl, isNew }: GitMountFormProps) => {
-  const [form, setForm] = useState<GitMount>({ ...mount });
-  const [errors, setErrors] = useState<Record<string, string>>({});
+const GitMountForm = ({ mount, onSave, onCancel }: GitMountFormProps) => {
+	const [remoteUrl, setRemoteUrl] = useState(mount.remote_url);
+	const [branch, setBranch] = useState(mount.branch || "");
+	const [mappings, setMappings] = useState<GitMountMapping[]>(
+		mount.mappings?.length
+			? mount.mappings
+			: [{ source_path: ".", target_path: "" }],
+	);
+	const [errors, setErrors] = useState<Record<string, string>>({});
 
-  const handleChange = (field: keyof GitMount, value: string) => {
-    setForm((prev) => ({ ...prev, [field]: value }));
-    if (errors[field]) {
-      setErrors((prev) => {
-        const next = { ...prev };
-        delete next[field];
-        return next;
-      });
-    }
-  };
+	const validate = (): boolean => {
+		const newErrors: Record<string, string> = {};
 
-  const handleSubmit = () => {
-    const newErrors: Record<string, string> = {};
-    
-    const urlError = validateUrl(form.remote_url);
-    if (urlError) newErrors.remote_url = urlError;
-    
-    const sourceError = validatePath(form.source_path || ".", false);
-    if (sourceError) newErrors.source_path = sourceError;
-    
-    const targetError = validatePath(form.target_path, true);
-    if (targetError) newErrors.target_path = targetError;
-    
-    if (Object.keys(newErrors).length > 0) {
-      setErrors(newErrors);
-      return;
-    }
-    
-    onSave(form);
-    if (isNew) {
-      setForm({ remote_url: "", source_path: ".", target_path: "", branch: "" });
-    }
-  };
+		if (!remoteUrl.trim()) {
+			newErrors.remote_url = "Git URL is required";
+		} else if (
+			!remoteUrl.startsWith("http://") &&
+			!remoteUrl.startsWith("https://") &&
+			!remoteUrl.startsWith("git@") &&
+			!remoteUrl.startsWith("ssh://")
+		) {
+			newErrors.remote_url =
+				"Must be a valid git URL (https://, git@, or ssh://)";
+		}
 
-  return (
-    <div className="git-mount-form">
-      <div className="form-row">
-        <label>Git URL</label>
-        <input
-          type="text"
-          value={form.remote_url}
-          onChange={(e) => handleChange("remote_url", e.target.value)}
-          placeholder="https://github.com/user/repo.git"
-          className={errors.remote_url ? "error" : ""}
-        />
-        <span className="hint">Repository URL (HTTPS or SSH)</span>
-        {errors.remote_url && <span className="error-text">{errors.remote_url}</span>}
-      </div>
+		mappings.forEach((m, i) => {
+			if (!m.target_path.trim()) {
+				newErrors[`mapping_${i}_target`] = "Target path is required";
+			}
+			if (m.source_path.includes("..")) {
+				newErrors[`mapping_${i}_source`] = "Source path cannot contain ..";
+			}
+			if (m.target_path.includes("..")) {
+				newErrors[`mapping_${i}_target`] = "Target path cannot contain ..";
+			}
+		});
 
-      <div className="form-row">
-        <label>Source Path</label>
-        <input
-          type="text"
-          value={form.source_path || "."}
-          onChange={(e) => handleChange("source_path", e.target.value)}
-          placeholder="e.g., . or configs/*.json"
-          className={errors.source_path ? "error" : ""}
-        />
-        <span className="hint">Relative path in repo (supports glob patterns)</span>
-        {errors.source_path && <span className="error-text">{errors.source_path}</span>}
-      </div>
+		setErrors(newErrors);
+		return Object.keys(newErrors).length === 0;
+	};
 
-      <div className="form-row">
-        <label>Target Path</label>
-        <input
-          type="text"
-          value={form.target_path}
-          onChange={(e) => handleChange("target_path", e.target.value)}
-          placeholder="e.g., /app/config"
-          className={errors.target_path ? "error" : ""}
-        />
-        <span className="hint">Use absolute path (e.g. /app/config). Relative paths need working_directory set in tool config.</span>
-        {errors.target_path && <span className="error-text">{errors.target_path}</span>}
-      </div>
+	const handleSubmit = () => {
+		if (!validate()) return;
+		onSave({
+			remote_url: remoteUrl.trim(),
+			branch: branch.trim() || undefined,
+			mappings: mappings.map((m) => ({
+				source_path: m.source_path.trim() || ".",
+				target_path: m.target_path.trim(),
+			})),
+		});
+	};
 
-      <div className="form-row">
-        <label>Branch (optional)</label>
-        <input
-          type="text"
-          value={form.branch || ""}
-          onChange={(e) => handleChange("branch", e.target.value)}
-          placeholder="e.g., main or v1.0"
-        />
-        <span className="hint">Branch or tag to checkout</span>
-      </div>
+	const addMapping = () => {
+		setMappings((prev) => [...prev, { source_path: ".", target_path: "" }]);
+	};
 
-      <div className="form-actions">
-        <button type="button" className="primary-button" onClick={handleSubmit}>
-          {isNew ? "Add" : "Save"}
-        </button>
-        <button type="button" className="secondary-button" onClick={onCancel}>
-          Cancel
-        </button>
-      </div>
-    </div>
-  );
-};
+	const updateMapping = (
+		index: number,
+		field: keyof GitMountMapping,
+		value: string,
+	) => {
+		setMappings((prev) => {
+			const next = [...prev];
+			next[index] = { ...next[index], [field]: value };
+			return next;
+		});
+		if (errors[`mapping_${index}_${field}`]) {
+			setErrors((prev) => {
+				const next = { ...prev };
+				delete next[`mapping_${index}_${field}`];
+				return next;
+			});
+		}
+	};
+
+	const removeMapping = (index: number) => {
+		setMappings((prev) => prev.filter((_, i) => i !== index));
+	};
+
+	return (
+		<div style={{ display: "flex", flexDirection: "column", gap: "0.75rem" }}>
+			<div className="form-row" style={{ gap: "0.5rem" }}>
+				<div style={{ flex: 2 }}>
+					<label style={{ fontSize: "0.875rem", fontWeight: 500 }}>
+						Repository URL
+					</label>
+					<input
+						type="text"
+						value={remoteUrl}
+						onChange={(e) => {
+							setRemoteUrl(e.target.value);
+							if (errors.remote_url) {
+								setErrors((prev) => {
+									const next = { ...prev };
+									delete next.remote_url;
+									return next;
+								});
+							}
+						}}
+						placeholder="https://github.com/user/repo.git"
+						className={`form-input ${errors.remote_url ? "error" : ""}`}
+					/>
+					{errors.remote_url && (
+						<span className="error-text">{errors.remote_url}</span>
+					)}
+				</div>
+				<div style={{ flex: 1 }}>
+					<label style={{ fontSize: "0.875rem", fontWeight: 500 }}>
+						Branch (optional)
+					</label>
+					<input
+						type="text"
+						value={branch}
+						onChange={(e) => setBranch(e.target.value)}
+						placeholder="main"
+						className="form-input"
+					/>
+				</div>
+			</div>
+
+			<div>
+				<label style={{ fontSize: "0.875rem", fontWeight: 500 }}>
+					Mappings
+				</label>
+				<p
+					className="muted"
+					style={{ margin: "0 0 0.5rem 0", fontSize: "0.8125rem" }}
+				>
+					Source paths within the repo and where to mount them in the container.
+				</p>
+				<div
+					style={{ display: "flex", flexDirection: "column", gap: "0.5rem" }}
+				>
+					{mappings.map((mapping, index) => (
+						<div
+							key={index}
+							className="form-row"
+							style={{ gap: "0.5rem", alignItems: "flex-start" }}
+						>
+							<input
+								type="text"
+								value={mapping.source_path}
+								onChange={(e) =>
+									updateMapping(index, "source_path", e.target.value)
+								}
+								placeholder="packages/api"
+								className={`form-input ${errors[`mapping_${index}_source`] ? "error" : ""}`}
+								style={{ flex: 1 }}
+							/>
+							<span
+								style={{
+									padding: "0.5rem 0",
+									color: "var(--muted)",
+									fontSize: "0.875rem",
+								}}
+							>
+								→
+							</span>
+							<input
+								type="text"
+								value={mapping.target_path}
+								onChange={(e) =>
+									updateMapping(index, "target_path", e.target.value)
+								}
+								placeholder="/app/api"
+								className={`form-input ${errors[`mapping_${index}_target`] ? "error" : ""}`}
+								style={{ flex: 1 }}
+							/>
+							{mappings.length > 1 && (
+								<button
+									type="button"
+									className="ghost-button small"
+									onClick={() => removeMapping(index)}
+									title="Remove mapping"
+								>
+									<Icon name="delete" size="sm" />
+								</button>
+							)}
+							{errors[`mapping_${index}_source`] && (
+								<span className="error-text">
+									{errors[`mapping_${index}_source`]}
+								</span>
+							)}
+							{errors[`mapping_${index}_target`] && (
+								<span className="error-text">
+									{errors[`mapping_${index}_target`]}
+								</span>
+							)}
+						</div>
+					))}
+				</div>
+				<button
+					type="button"
+					className="secondary-button small"
+					onClick={addMapping}
+					style={{ marginTop: "0.5rem" }}
+				>
+					<Icon name="add" size="sm" />
+					Add Mapping
+				</button>
+			</div>
+
+			<div
+				className="form-actions"
+				style={{ display: "flex", gap: "0.5rem", marginTop: "0.5rem" }}
+			>
+				<button type="button" className="primary-button" onClick={handleSubmit}>
+					Save
+				</button>
+				<button type="button" className="secondary-button" onClick={onCancel}>
+					Cancel
+				</button>
+			</div>
+		</div>
+	);
+};

apps/web/src/components/manifest-editor.tsx

@@ -1,4 +1,4 @@
-import { useState, useEffect, useCallback } from "react";
+import { useState, useEffect, useCallback, useRef } from "react";
 import { Icon } from "./icon";
 import { extractErrorMessage } from "../utils/errors";
 import {
@@ -170,11 +170,20 @@ export const ManifestEditor = ({
 		baseDefinitionId,
 	]);
 
-	// Notify parent of changes
+	// Notify parent of changes — only when built manifest actually differs
+	// from what we last sent, to avoid feedback loops with the manifest prop.
+	const lastSentRef = useRef<string>("");
+	const onChangeRef = useRef(onChange);
+	onChangeRef.current = onChange;
+
 	useEffect(() => {
 		const m = buildManifest();
-		onChange(m);
-	}, [buildManifest, onChange]);
+		const serialized = JSON.stringify(m);
+		if (serialized !== lastSentRef.current) {
+			lastSentRef.current = serialized;
+			onChangeRef.current(m);
+		}
+	}, [buildManifest]);
 
 	const handlePreview = async () => {
 		if (!definitionId) {

apps/web/src/components/terminal-session-tabs.test.tsx

@@ -0,0 +1,161 @@
+import { render, screen, fireEvent, cleanup } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import {
+  TerminalSessionTabs,
+  type TerminalSessionInfo,
+} from "./terminal-session-tabs";
+
+const mockSessions: TerminalSessionInfo[] = [
+  { id: "s1", name: "Session 1", status: "connected" },
+  { id: "s2", name: "Session 2", status: "connecting" },
+  { id: "s3", name: "Session 3", status: "disconnected" },
+];
+
+afterEach(() => {
+  cleanup();
+});
+
+describe("TerminalSessionTabs", () => {
+  it("renders all tabs", () => {
+    render(
+      <TerminalSessionTabs
+        sessions={mockSessions}
+        activeSessionId="s1"
+        onSelect={vi.fn()}
+        onClose={vi.fn()}
+        onCreate={vi.fn()}
+        onRename={vi.fn()}
+      />
+    );
+
+    expect(screen.getByText("Session 1")).toBeInTheDocument();
+    expect(screen.getByText("Session 2")).toBeInTheDocument();
+    expect(screen.getByText("Session 3")).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: /new session/i })).toBeInTheDocument();
+  });
+
+  it("clicking a tab calls onSelect", () => {
+    const onSelect = vi.fn();
+    render(
+      <TerminalSessionTabs
+        sessions={mockSessions}
+        activeSessionId="s1"
+        onSelect={onSelect}
+        onClose={vi.fn()}
+        onCreate={vi.fn()}
+        onRename={vi.fn()}
+      />
+    );
+
+    fireEvent.click(screen.getAllByText("Session 2")[0]);
+    expect(onSelect).toHaveBeenCalledWith("s2");
+  });
+
+  it("close button calls onClose after confirmation", () => {
+    const onClose = vi.fn();
+    render(
+      <TerminalSessionTabs
+        sessions={mockSessions}
+        activeSessionId="s1"
+        onSelect={vi.fn()}
+        onClose={onClose}
+        onCreate={vi.fn()}
+        onRename={vi.fn()}
+      />
+    );
+
+    const closeButton = screen.getByLabelText("Close session Session 1");
+    // First click shows confirm
+    fireEvent.click(closeButton);
+    expect(screen.getByText("Close?")).toBeInTheDocument();
+
+    // Click confirm text
+    fireEvent.click(screen.getByText("Close?"));
+    expect(onClose).toHaveBeenCalledWith("s1");
+  });
+
+  it("double-click enables rename and Enter commits", () => {
+    const onRename = vi.fn();
+    render(
+      <TerminalSessionTabs
+        sessions={mockSessions}
+        activeSessionId="s1"
+        onSelect={vi.fn()}
+        onClose={vi.fn()}
+        onCreate={vi.fn()}
+        onRename={onRename}
+      />
+    );
+
+    fireEvent.doubleClick(screen.getAllByText("Session 1")[0]);
+    const input = screen.getByLabelText("Rename session");
+    expect(input).toBeInTheDocument();
+
+    fireEvent.change(input, { target: { value: "Renamed" } });
+    fireEvent.keyDown(input, { key: "Enter" });
+    expect(onRename).toHaveBeenCalledWith("s1", "Renamed");
+  });
+
+  it("double-click enables rename and Escape cancels", () => {
+    const onRename = vi.fn();
+    render(
+      <TerminalSessionTabs
+        sessions={mockSessions}
+        activeSessionId="s1"
+        onSelect={vi.fn()}
+        onClose={vi.fn()}
+        onCreate={vi.fn()}
+        onRename={onRename}
+      />
+    );
+
+    fireEvent.doubleClick(screen.getAllByText("Session 1")[0]);
+    const input = screen.getByLabelText("Rename session");
+    fireEvent.change(input, { target: { value: "Renamed" } });
+    fireEvent.keyDown(input, { key: "Escape" });
+    expect(onRename).not.toHaveBeenCalled();
+    expect(screen.getByText("Session 1")).toBeInTheDocument();
+  });
+
+  it("plus button is disabled at 5 sessions", () => {
+    const fiveSessions: TerminalSessionInfo[] = Array.from({ length: 5 }, (_, i) => ({
+      id: `s${i + 1}`,
+      name: `Session ${i + 1}`,
+      status: "connected",
+    }));
+
+    render(
+      <TerminalSessionTabs
+        sessions={fiveSessions}
+        activeSessionId="s1"
+        onSelect={vi.fn()}
+        onClose={vi.fn()}
+        onCreate={vi.fn()}
+        onRename={vi.fn()}
+      />
+    );
+
+    const newButton = screen.getByRole("button", { name: /new session/i });
+    expect(newButton).toBeDisabled();
+  });
+
+  it("status dot reflects connection state", () => {
+    render(
+      <TerminalSessionTabs
+        sessions={mockSessions}
+        activeSessionId="s1"
+        onSelect={vi.fn()}
+        onClose={vi.fn()}
+        onCreate={vi.fn()}
+        onRename={vi.fn()}
+      />
+    );
+
+    const tabs = screen.getAllByRole("tab");
+    expect(tabs).toHaveLength(3);
+    expect(tabs[0].querySelector(".connected")).toBeInTheDocument();
+    expect(tabs[1].querySelector(".connecting")).toBeInTheDocument();
+    expect(tabs[2].querySelector(".disconnected")).toBeInTheDocument();
+  });
+});

apps/web/src/components/terminal-session-tabs.tsx

@@ -0,0 +1,167 @@
+import React, { useState, useRef, useCallback } from "react";
+
+export interface TerminalSessionInfo {
+	id: string;
+	name: string;
+	status: "connecting" | "connected" | "disconnected" | "error" | "resetting";
+}
+
+export interface TerminalSessionTabsProps {
+	sessions: TerminalSessionInfo[];
+	activeSessionId: string;
+	onSelect: (sessionId: string) => void;
+	onClose: (sessionId: string) => void;
+	onCreate: () => void;
+	onRename: (sessionId: string, newName: string) => void;
+	isMobile?: boolean;
+}
+
+export const TerminalSessionTabs: React.FC<TerminalSessionTabsProps> = ({
+	sessions,
+	activeSessionId,
+	onSelect,
+	onClose,
+	onCreate,
+	onRename,
+	isMobile = false,
+}) => {
+	const [renamingId, setRenamingId] = useState<string | null>(null);
+	const [renameValue, setRenameValue] = useState("");
+	const [confirmCloseId, setConfirmCloseId] = useState<string | null>(null);
+	const renameInputRef = useRef<HTMLInputElement>(null);
+	const scrollRef = useRef<HTMLDivElement>(null);
+
+	const handleDoubleClick = useCallback((session: TerminalSessionInfo) => {
+		setRenamingId(session.id);
+		setRenameValue(session.name);
+		requestAnimationFrame(() => {
+			renameInputRef.current?.focus();
+			renameInputRef.current?.select();
+		});
+	}, []);
+
+	const commitRename = useCallback(() => {
+		if (renamingId && renameValue.trim()) {
+			onRename(renamingId, renameValue.trim());
+		}
+		setRenamingId(null);
+		setRenameValue("");
+	}, [renamingId, renameValue, onRename]);
+
+	const cancelRename = useCallback(() => {
+		setRenamingId(null);
+		setRenameValue("");
+	}, []);
+
+	const handleRenameKeyDown = useCallback(
+		(e: React.KeyboardEvent<HTMLInputElement>) => {
+			if (e.key === "Enter") {
+				commitRename();
+			} else if (e.key === "Escape") {
+				cancelRename();
+			}
+		},
+		[commitRename, cancelRename],
+	);
+
+	const handleCloseClick = useCallback(
+		(e: React.MouseEvent, sessionId: string) => {
+			e.stopPropagation();
+			if (confirmCloseId === sessionId) {
+				setConfirmCloseId(null);
+				onClose(sessionId);
+			} else {
+				setConfirmCloseId(sessionId);
+				// Auto-dismiss confirm after 3s
+				setTimeout(() => {
+					setConfirmCloseId((prev) => (prev === sessionId ? null : prev));
+				}, 3000);
+			}
+		},
+		[confirmCloseId, onClose],
+	);
+
+	const isMaxSessions = sessions.length >= 5;
+
+	return (
+		<div
+			className={`terminal-session-tabs ${isMobile ? "mobile" : ""}`}
+			role="tablist"
+			aria-label="Terminal sessions"
+		>
+			<div className="terminal-session-tabs-scroll" ref={scrollRef}>
+				{sessions.map((session) => {
+					const isActive = session.id === activeSessionId;
+					const isRenaming = renamingId === session.id;
+					const isConfirmingClose = confirmCloseId === session.id;
+
+					return (
+						<div
+							key={session.id}
+							className={`terminal-session-tab ${isActive ? "active" : ""}`}
+							role="tab"
+							aria-selected={isActive}
+							onClick={() => onSelect(session.id)}
+							onDoubleClick={() => handleDoubleClick(session)}
+							title={isRenaming ? "" : `${session.name} (${session.status})`}
+						>
+							<span
+								className={`terminal-session-tab-status ${session.status}`}
+								aria-hidden="true"
+							/>
+							{isRenaming ? (
+								<input
+									ref={renameInputRef}
+									className="terminal-session-tab-input"
+									value={renameValue}
+									onChange={(e) => setRenameValue(e.target.value)}
+									onKeyDown={handleRenameKeyDown}
+									onBlur={commitRename}
+									onClick={(e) => e.stopPropagation()}
+									aria-label="Rename session"
+								/>
+							) : (
+								<span className="terminal-session-tab-name">
+									{session.name}
+								</span>
+							)}
+						{isConfirmingClose ? (
+							<button
+								className="terminal-session-tab-confirm"
+								onClick={(e) => {
+									e.stopPropagation();
+									setConfirmCloseId(null);
+									onClose(session.id);
+								}}
+								type="button"
+							>
+								Close?
+							</button>
+						) : (
+							<button
+								className="terminal-session-tab-close"
+								onClick={(e) => handleCloseClick(e, session.id)}
+								type="button"
+								aria-label={`Close session ${session.name}`}
+								tabIndex={-1}
+							>
+								×
+							</button>
+						)}
+						</div>
+					);
+				})}
+				<button
+					className="terminal-session-tab new-session"
+					onClick={onCreate}
+					disabled={isMaxSessions}
+					type="button"
+					aria-label="New session"
+					title={isMaxSessions ? "Maximum 5 sessions reached" : "New session"}
+				>
+					+
+				</button>
+			</div>
+		</div>
+	);
+};

apps/web/src/hooks/use-terminal-sessions.ts

@@ -0,0 +1,145 @@
+import { useCallback, useEffect, useState } from "react";
+import {
+	listTerminalSessions,
+	createTerminalSession,
+	closeTerminalSession,
+	resetTerminalSession,
+	renameTerminalSession,
+	type TerminalSession,
+} from "../api/terminal";
+
+export interface UseTerminalSessionsResult {
+	sessions: TerminalSession[];
+	activeSessionId: string | null;
+	setActiveSessionId: (id: string) => void;
+	createSession: (name?: string) => Promise<TerminalSession | null>;
+	closeSession: (sessionId: string) => Promise<void>;
+	renameSession: (sessionId: string, name: string) => Promise<void>;
+	resetSession: (sessionId: string) => Promise<void>;
+	loading: boolean;
+	error: string | null;
+}
+
+export function useTerminalSessions(
+	instanceId: string,
+): UseTerminalSessionsResult {
+	const [sessions, setSessions] = useState<TerminalSession[]>([]);
+	const [activeSessionId, setActiveSessionId] = useState<string | null>(null);
+	const [loading, setLoading] = useState(true);
+	const [error, setError] = useState<string | null>(null);
+
+	const loadSessions = useCallback(async () => {
+		setLoading(true);
+		setError(null);
+		try {
+			const sess = await listTerminalSessions(instanceId);
+			setSessions(sess);
+			if (sess.length > 0 && !activeSessionId) {
+				setActiveSessionId(sess[0].id);
+			}
+		} catch (err) {
+			setError(err instanceof Error ? err.message : "Failed to load sessions");
+		} finally {
+			setLoading(false);
+		}
+	}, [instanceId, activeSessionId]);
+
+	const createSession = useCallback(
+		async (name?: string) => {
+			setError(null);
+			try {
+				const newSession = await createTerminalSession(instanceId, name);
+				const session: TerminalSession = {
+					id: newSession.id,
+					name: newSession.name,
+					status: newSession.status,
+					has_websockets: false,
+					created_at: newSession.created_at,
+					last_activity_at: null,
+				};
+				setSessions((prev) => [...prev, session]);
+				setActiveSessionId(session.id);
+				return session;
+			} catch (err) {
+				const msg =
+					err instanceof Error ? err.message : "Failed to create session";
+				setError(msg);
+				return null;
+			}
+		},
+		[instanceId],
+	);
+
+	const closeSession = useCallback(
+		async (sessionId: string) => {
+			setError(null);
+			try {
+				await closeTerminalSession(instanceId, sessionId);
+				setSessions((prev) => {
+					const filtered = prev.filter((s) => s.id !== sessionId);
+					if (activeSessionId === sessionId && filtered.length > 0) {
+						setActiveSessionId(filtered[0].id);
+					} else if (filtered.length === 0) {
+						setActiveSessionId(null);
+					}
+					return filtered;
+				});
+			} catch (err) {
+				setError(
+					err instanceof Error ? err.message : "Failed to close session",
+				);
+			}
+		},
+		[instanceId, activeSessionId],
+	);
+
+	const renameSession = useCallback(
+		async (sessionId: string, name: string) => {
+			setError(null);
+			try {
+				await renameTerminalSession(instanceId, sessionId, name);
+				setSessions((prev) =>
+					prev.map((s) => (s.id === sessionId ? { ...s, name } : s)),
+				);
+			} catch (err) {
+				setError(
+					err instanceof Error ? err.message : "Failed to rename session",
+				);
+			}
+		},
+		[instanceId],
+	);
+
+	const resetSession = useCallback(
+		async (sessionId: string) => {
+			setError(null);
+			try {
+				await resetTerminalSession(instanceId, sessionId);
+				// Refetch to get updated session info
+				await loadSessions();
+			} catch (err) {
+				setError(
+					err instanceof Error ? err.message : "Failed to reset session",
+				);
+			}
+		},
+		[instanceId, loadSessions],
+	);
+
+	// Initial load
+	useEffect(() => {
+		void loadSessions();
+	}, [loadSessions]);
+
+	return {
+		sessions,
+		activeSessionId,
+		setActiveSessionId,
+		createSession,
+		closeSession,
+		renameSession,
+		resetSession,
+		loading,
+		error,
+	};
+}

apps/web/src/pages/terminal.tsx

@@ -1,50 +1,310 @@
-import React from "react";
+import React, { useCallback, useEffect, useRef, useState } from "react";
 import { useNavigate, useParams } from "react-router-dom";
-import { TerminalComponent } from "../components/terminal";
-import { MobileTerminalWrapper } from "../components/mobile-terminal-wrapper";
+import { TerminalComponent, type TerminalRef } from "../components/terminal";
+import {
+	TerminalSessionTabs,
+	type TerminalSessionInfo,
+} from "../components/terminal-session-tabs";
 import { useMobileViewport } from "../hooks/use-mobile-viewport";
+import { useAutoHide } from "../hooks/use-auto-hide";
+import { useTerminalSessions } from "../hooks/use-terminal-sessions";
+import type { TerminalSession } from "../api/terminal";
+
+const SESSIONS_TO_INFO = (sessions: TerminalSession[]): TerminalSessionInfo[] =>
+	sessions.map((s) => ({
+		id: s.id,
+		name: s.name,
+		status: s.status as TerminalSessionInfo["status"],
+	}));
 
 export const TerminalPage: React.FC = () => {
-  const { instanceId } = useParams<{ instanceId: string }>();
-  const navigate = useNavigate();
-  const isMobile = useMobileViewport();
+	const { instanceId } = useParams<{
+		instanceId: string;
+	}>();
+	const navigate = useNavigate();
+	const isMobile = useMobileViewport();
+	const [isFullscreen, setIsFullscreen] = useState(false);
+	const terminalRefs = useRef<Record<string, React.RefObject<TerminalRef>>>({});
+	const headerAutoHide = useAutoHide({ timeout: 3000, enabled: isMobile });
 
-  if (!instanceId) {
-    return (
-      <section className="stack">
-        <h1>Terminal</h1>
-        <p className="muted">No instance ID provided.</p>
-      </section>
-    );
-  }
+	const {
+		sessions,
+		activeSessionId,
+		setActiveSessionId,
+		createSession,
+		closeSession,
+		renameSession,
+		resetSession,
+		loading,
+		error,
+	} = useTerminalSessions(instanceId ?? "");
 
-  if (isMobile) {
-    return (
-      <MobileTerminalWrapper
-        instanceId={instanceId}
-        onBack={() => navigate(-1)}
-        onClose={() => navigate(-1)}
-      />
-    );
-  }
+	// Auto-create default session if none exist after loading completes
+	useEffect(() => {
+		if (!loading && sessions.length === 0 && !error && instanceId) {
+			void createSession("Session 1");
+		}
+	}, [loading, sessions.length, error, instanceId, createSession]);
 
-  return (
-    <section className="terminal-page">
-      <div className="terminal-page-header">
-        <button
-          className="secondary-button"
-          onClick={() => navigate(-1)}
-          type="button"
-        >
-          Back
-        </button>
-        <h1>Terminal</h1>
-      </div>
-      <TerminalComponent
-        instanceId={instanceId}
-        onClose={() => navigate(-1)}
-        isMobile={false}
-      />
-    </section>
-  );
+	// Ensure refs map is kept in sync with sessions
+	useEffect(() => {
+		for (const session of sessions) {
+			if (!terminalRefs.current[session.id]) {
+				terminalRefs.current[session.id] = React.createRef<TerminalRef>();
+			}
+		}
+		// Clean up refs for closed sessions
+		const currentIds = new Set(sessions.map((s) => s.id));
+		for (const id of Object.keys(terminalRefs.current)) {
+			if (!currentIds.has(id)) {
+				delete terminalRefs.current[id];
+			}
+		}
+	}, [sessions]);
+
+	// Fit and focus active terminal when switching tabs
+	useEffect(() => {
+		if (activeSessionId && terminalRefs.current[activeSessionId]) {
+			const ref = terminalRefs.current[activeSessionId];
+			// Small delay to allow display:block to apply
+			const timer = setTimeout(() => {
+				ref.current?.fit();
+				ref.current?.focus();
+			}, 50);
+			return () => clearTimeout(timer);
+		}
+	}, [activeSessionId]);
+
+	// Keyboard shortcuts
+	useEffect(() => {
+		const handleKeyDown = (e: KeyboardEvent) => {
+			const isAltShift = e.altKey && e.shiftKey && !e.ctrlKey && !e.metaKey;
+			if (!isAltShift) return;
+
+			switch (e.key.toLowerCase()) {
+				case "n":
+					e.preventDefault();
+					if (sessions.length < 5) {
+						void createSession(`Session ${sessions.length + 1}`);
+					}
+					break;
+				case "w":
+					e.preventDefault();
+					if (
+						activeSessionId &&
+						window.confirm("Close this terminal session?")
+					) {
+						void closeSession(activeSessionId);
+					}
+					break;
+				case "arrowleft":
+					e.preventDefault();
+					if (activeSessionId) {
+						const idx = sessions.findIndex((s) => s.id === activeSessionId);
+						if (idx > 0) {
+							setActiveSessionId(sessions[idx - 1].id);
+						}
+					}
+					break;
+				case "arrowright":
+					e.preventDefault();
+					if (activeSessionId) {
+						const idx = sessions.findIndex((s) => s.id === activeSessionId);
+						if (idx < sessions.length - 1) {
+							setActiveSessionId(sessions[idx + 1].id);
+						}
+					}
+					break;
+				case "r":
+					e.preventDefault();
+					if (activeSessionId) {
+						void resetSession(activeSessionId);
+					}
+					break;
+				case "f":
+					e.preventDefault();
+					setIsFullscreen((prev) => !prev);
+					break;
+				default:
+					break;
+			}
+		};
+
+		window.addEventListener("keydown", handleKeyDown);
+		return () => window.removeEventListener("keydown", handleKeyDown);
+	}, [
+		sessions,
+		activeSessionId,
+		createSession,
+		closeSession,
+		resetSession,
+		setActiveSessionId,
+	]);
+
+	// Exit fullscreen on Escape
+	useEffect(() => {
+		if (!isFullscreen) return;
+		const handleEscape = (e: KeyboardEvent) => {
+			if (e.key === "Escape") {
+				setIsFullscreen(false);
+			}
+		};
+		window.addEventListener("keydown", handleEscape);
+		return () => window.removeEventListener("keydown", handleEscape);
+	}, [isFullscreen]);
+
+	const handleSelect = useCallback(
+		(sessionId: string) => {
+			setActiveSessionId(sessionId);
+		},
+		[setActiveSessionId],
+	);
+
+	const handleClose = useCallback(
+		async (sessionId: string) => {
+			await closeSession(sessionId);
+		},
+		[closeSession],
+	);
+
+	const handleCreate = useCallback(() => {
+		void createSession(`Session ${sessions.length + 1}`);
+	}, [createSession, sessions.length]);
+
+	const handleRename = useCallback(
+		(sessionId: string, newName: string) => {
+			void renameSession(sessionId, newName);
+		},
+		[renameSession],
+	);
+
+	if (!instanceId) {
+		return (
+			<section className="stack">
+				<h1>Terminal</h1>
+				<p className="muted">No instance ID provided.</p>
+			</section>
+		);
+	}
+
+	const sessionInfos = SESSIONS_TO_INFO(sessions);
+
+	if (isMobile) {
+		return (
+			<section
+				className={`terminal-page mobile ${isFullscreen ? "fullscreen" : ""}`}
+			>
+				<div
+					className={`terminal-page-header mobile-header ${headerAutoHide.isVisible ? "visible" : "hidden"}`}
+					onClick={() => headerAutoHide.show()}
+				>
+					<button
+						className="secondary-button"
+						onClick={() => navigate(-1)}
+						type="button"
+					>
+						Back
+					</button>
+					<h1>Terminal</h1>
+					<button
+						className="secondary-button"
+						onClick={() => setIsFullscreen((p) => !p)}
+						type="button"
+					>
+						{isFullscreen ? "Exit" : "Fullscreen"}
+					</button>
+				</div>
+				<div
+					className={`mobile-tabs-container ${headerAutoHide.isVisible ? "visible" : "hidden"}`}
+					onClick={() => headerAutoHide.show()}
+				>
+					<TerminalSessionTabs
+						sessions={sessionInfos}
+						activeSessionId={activeSessionId ?? ""}
+						onSelect={handleSelect}
+						onClose={handleClose}
+						onCreate={handleCreate}
+						onRename={handleRename}
+						isMobile={true}
+					/>
+				</div>
+				<div className="terminal-page-content">
+					{error && <div className="terminal-error-banner">{error}</div>}
+					{sessions
+						.filter((session) => session.id === activeSessionId)
+						.map((session) => (
+							<div key={session.id} className="terminal-instance active">
+								<TerminalComponent
+									ref={terminalRefs.current[session.id]}
+									instanceId={instanceId}
+									sessionId={session.id}
+									onClose={() => handleClose(session.id)}
+									isMobile={true}
+								/>
+							</div>
+						))}
+					{sessions.length === 0 && !loading && (
+						<div className="terminal-empty-state">
+							<p>No terminal sessions. Press Alt+Shift+N to create one.</p>
+						</div>
+					)}
+				</div>
+			</section>
+		);
+	}
+
+	return (
+		<section className={`terminal-page ${isFullscreen ? "fullscreen" : ""}`}>
+			{!isFullscreen && (
+				<div className="terminal-page-header">
+					<button
+						className="secondary-button"
+						onClick={() => navigate(-1)}
+						type="button"
+					>
+						Back
+					</button>
+					<h1>Terminal</h1>
+					<button
+						className="secondary-button"
+						onClick={() => setIsFullscreen((p) => !p)}
+						type="button"
+						title="Toggle fullscreen (Alt+Shift+F)"
+					>
+						{isFullscreen ? "Exit Fullscreen" : "Fullscreen"}
+					</button>
+				</div>
+			)}
+			<TerminalSessionTabs
+				sessions={sessionInfos}
+				activeSessionId={activeSessionId ?? ""}
+				onSelect={handleSelect}
+				onClose={handleClose}
+				onCreate={handleCreate}
+				onRename={handleRename}
+				isMobile={false}
+			/>
+			<div className="terminal-page-content">
+				{error && <div className="terminal-error-banner">{error}</div>}
+				{sessions
+					.filter((session) => session.id === activeSessionId)
+					.map((session) => (
+						<div key={session.id} className="terminal-instance active">
+							<TerminalComponent
+								ref={terminalRefs.current[session.id]}
+								instanceId={instanceId}
+								sessionId={session.id}
+								onClose={() => handleClose(session.id)}
+								isMobile={false}
+							/>
+						</div>
+					))}
+				{sessions.length === 0 && !loading && (
+					<div className="terminal-empty-state">
+						<p>No terminal sessions. Press Alt+Shift+N to create one.</p>
+					</div>
+				)}
+			</div>
+		</section>
+	);
 };

apps/web/src/pages/tool-workshop.test.tsx

@@ -1,399 +0,0 @@
-import { cleanup, fireEvent, render, screen, waitFor, within } from "@testing-library/react";
-import { afterEach, describe, expect, it, vi } from "vitest";
-
-import { ToolWorkshopPage } from "./tool-workshop";
-import * as toolTypesApi from "../api/tool_types";
-import * as toolConfigsApi from "../api/tool_configs";
-import * as configFoldersApi from "../api/config_folders";
-
-const mockToolTypes = [
-  {
-    id: "type-1",
-    name: "code-server",
-    display_name: "VS Code Server",
-    description: "VS Code in browser",
-    category: "editor",
-    interface_type: "web",
-    requires_port: true,
-    default_port: 8443,
-    definition_type: "compose",
-    compose_template: "version: '3.8'\\nservices:\\n  app:\\n    image: codercom/code-server",
-    dockerfile_template: null,
-    build_context: null,
-    readiness_probe: null,
-    required_variables: ["REPO_PATH"],
-    is_builtin: true,
-    created_by_id: null,
-    created_at: "2024-01-01T00:00:00Z",
-    updated_at: "2024-01-01T00:00:00Z",
-  },
-  {
-    id: "type-2",
-    name: "custom-tool",
-    display_name: "Custom Tool",
-    description: "My custom tool",
-    category: "utility",
-    interface_type: "terminal",
-    requires_port: false,
-    default_port: 8080,
-    definition_type: "dockerfile",
-    compose_template: null,
-    dockerfile_template: "FROM python:3.11",
-    build_context: null,
-    readiness_probe: {
-      command: "python --version",
-      timeout: 30,
-      interval: 2,
-    },
-    required_variables: [],
-    is_builtin: false,
-    created_by_id: "user-1",
-    created_at: "2024-01-01T00:00:00Z",
-    updated_at: "2024-01-01T00:00:00Z",
-  },
-];
-
-const mockConfigs = [
-  {
-    id: "config-1",
-    tool_type_id: "type-1",
-    project_id: null,
-    key: "OPENAI_API_KEY",
-    value: "sk-test123",
-    config_type: "env",
-    file_path: null,
-    port_override: null,
-    start_command: null,
-    working_directory: null,
-    environment_variables: {},
-    volumes: [],
-  },
-  {
-    id: "config-2",
-    tool_type_id: "type-2",
-    project_id: null,
-    key: "advanced-config",
-    value: "test-value",
-    config_type: "env",
-    file_path: null,
-    port_override: 9090,
-    start_command: "python app.py",
-    working_directory: "/app",
-    environment_variables: { DEBUG: "true" },
-    volumes: [{ source: "data", target: "/data", type: "bind" }],
-  },
-];
-
-const mockFolders = [
-  {
-    id: "folder-1",
-    user_id: "user-1",
-    name: "my-dotfiles",
-    description: "My personal config files",
-    mount_path: "/home/user",
-    files: { ".zshrc": "export ZSH=\"$HOME/.oh-my-zsh\"" },
-    project_overrides: {},
-    is_active: true,
-    created_at: "2024-01-01T00:00:00Z",
-    updated_at: "2024-01-01T00:00:00Z",
-  },
-  {
-    id: "folder-2",
-    user_id: "user-1",
-    name: "project-configs",
-    description: "Project specific configs",
-    mount_path: "/workspace",
-    files: { ".env": "API_URL=http://localhost:8080" },
-    project_overrides: {
-      "proj-1": {
-        mount_path: "/app",
-        files: { ".env": "API_URL=http://prod.api" },
-      },
-    },
-    is_active: false,
-    created_at: "2024-01-01T00:00:00Z",
-    updated_at: "2024-01-01T00:00:00Z",
-  },
-];
-
-afterEach(() => {
-  cleanup();
-  vi.restoreAllMocks();
-});
-
-describe("ToolWorkshopPage", () => {
-  it("renders loading state initially", () => {
-    vi.spyOn(toolTypesApi, "listToolTypes").mockImplementation(() => new Promise(() => {}));
-    vi.spyOn(toolConfigsApi, "listToolConfigs").mockImplementation(() => new Promise(() => {}));
-    vi.spyOn(configFoldersApi, "listConfigFolders").mockImplementation(() => new Promise(() => {}));
-
-    render(<ToolWorkshopPage />);
-    expect(screen.getByText(/loading/i)).toBeInTheDocument();
-  });
-
-  it("renders tool types tab by default", async () => {
-    vi.spyOn(toolTypesApi, "listToolTypes").mockResolvedValue(mockToolTypes as unknown as toolTypesApi.ToolType[]);
-    vi.spyOn(toolConfigsApi, "listToolConfigs").mockResolvedValue(mockConfigs as unknown as toolConfigsApi.ToolConfig[]);
-    vi.spyOn(configFoldersApi, "listConfigFolders").mockResolvedValue(mockFolders as unknown as configFoldersApi.ConfigFolder[]);
-
-    render(<ToolWorkshopPage />);
-
-    await waitFor(() => {
-      expect(screen.getByText("VS Code Server")).toBeInTheDocument();
-    });
-    expect(screen.getByText("Custom Tool")).toBeInTheDocument();
-  });
-
-  it("switches to configs tab", async () => {
-    vi.spyOn(toolTypesApi, "listToolTypes").mockResolvedValue(mockToolTypes as unknown as toolTypesApi.ToolType[]);
-    vi.spyOn(toolConfigsApi, "listToolConfigs").mockResolvedValue(mockConfigs as unknown as toolConfigsApi.ToolConfig[]);
-    vi.spyOn(configFoldersApi, "listConfigFolders").mockResolvedValue(mockFolders as unknown as configFoldersApi.ConfigFolder[]);
-
-    render(<ToolWorkshopPage />);
-
-    await waitFor(() => {
-      expect(screen.getByText("VS Code Server")).toBeInTheDocument();
-    });
-
-    fireEvent.click(screen.getByText("VS Code Server"));
-
-    await waitFor(() => {
-      expect(screen.getByRole("button", { name: /configs/i })).toBeInTheDocument();
-    });
-
-    fireEvent.click(screen.getByRole("button", { name: /configs/i }));
-
-    await waitFor(() => {
-      expect(screen.getByText("OPENAI_API_KEY")).toBeInTheDocument();
-    });
-
-    fireEvent.click(screen.getByRole("button", { name: /add config/i }));
-
-    expect(screen.getByPlaceholderText("e.g., OPENAI_API_KEY")).toBeInTheDocument();
-    expect(screen.getByPlaceholderText(/Enter value/i)).toBeInTheDocument();
-  });
-
-  it("creates config with advanced fields", async () => {
-    vi.spyOn(toolTypesApi, "listToolTypes").mockResolvedValue(mockToolTypes as unknown as toolTypesApi.ToolType[]);
-    const configsListMock = vi.spyOn(toolConfigsApi, "listToolConfigs").mockResolvedValue(mockConfigs as unknown as toolConfigsApi.ToolConfig[]);
-    const createMock = vi.spyOn(toolConfigsApi, "createToolConfig").mockResolvedValue(mockConfigs[1] as unknown as toolConfigsApi.ToolConfig);
-    vi.spyOn(configFoldersApi, "listConfigFolders").mockResolvedValue(mockFolders as unknown as configFoldersApi.ConfigFolder[]);
-
-    render(<ToolWorkshopPage />);
-
-    await waitFor(() => {
-      expect(screen.getByText("VS Code Server")).toBeInTheDocument();
-    });
-
-    fireEvent.click(screen.getByText("VS Code Server"));
-
-    await waitFor(() => {
-      expect(screen.getByRole("button", { name: /configs/i })).toBeInTheDocument();
-    });
-
-    fireEvent.click(screen.getByRole("button", { name: /configs/i }));
-
-    await waitFor(() => {
-      expect(screen.getByText("OPENAI_API_KEY")).toBeInTheDocument();
-    });
-
-    fireEvent.click(screen.getByRole("button", { name: /add config/i }));
-
-    fireEvent.change(screen.getByPlaceholderText("e.g., OPENAI_API_KEY"), {
-      target: { value: "MY_CONFIG" },
-    });
-    fireEvent.change(screen.getByPlaceholderText(/Enter value/i), {
-      target: { value: "my-value" },
-    });
-    fireEvent.change(screen.getByPlaceholderText("e.g., 8080"), {
-      target: { value: "9090" },
-    });
-    fireEvent.change(screen.getByPlaceholderText("e.g., npm start"), {
-      target: { value: "python app.py" },
-    });
-
-    fireEvent.click(screen.getByRole("button", { name: /add$/i }));
-
-    await waitFor(() => {
-      expect(createMock).toHaveBeenCalledWith(
-        expect.objectContaining({
-          key: "MY_CONFIG",
-          value: "my-value",
-          port_override: 9090,
-          start_command: "python app.py",
-        })
-      );
-    });
-    expect(configsListMock).toHaveBeenCalledTimes(2);
-  });
-
-  it("opens folder creation form", async () => {
-    vi.spyOn(toolTypesApi, "listToolTypes").mockResolvedValue(mockToolTypes as unknown as toolTypesApi.ToolType[]);
-    vi.spyOn(toolConfigsApi, "listToolConfigs").mockResolvedValue(mockConfigs as unknown as toolConfigsApi.ToolConfig[]);
-    vi.spyOn(configFoldersApi, "listConfigFolders").mockResolvedValue(mockFolders as unknown as configFoldersApi.ConfigFolder[]);
-
-    render(<ToolWorkshopPage />);
-
-    await waitFor(() => {
-      expect(screen.getByText("VS Code Server")).toBeInTheDocument();
-    });
-
-    fireEvent.click(screen.getByText("VS Code Server"));
-
-    await waitFor(() => {
-      expect(screen.getByRole("button", { name: /folders/i })).toBeInTheDocument();
-    });
-
-    fireEvent.click(screen.getByRole("button", { name: /folders/i }));
-
-    await waitFor(() => {
-      expect(screen.getByText("my-dotfiles")).toBeInTheDocument();
-    });
-
-    fireEvent.click(screen.getByRole("button", { name: /create folder/i }));
-
-    expect(screen.getByPlaceholderText("e.g., my-dotfiles")).toBeInTheDocument();
-    expect(screen.getByPlaceholderText("e.g., /home/user")).toBeInTheDocument();
-  });
-
-  it("creates config folder successfully", async () => {
-    const foldersListMock = vi.spyOn(configFoldersApi, "listConfigFolders").mockResolvedValue(mockFolders as unknown as configFoldersApi.ConfigFolder[]);
-    const createMock = vi.spyOn(configFoldersApi, "createConfigFolder").mockResolvedValue(mockFolders[0] as unknown as configFoldersApi.ConfigFolder);
-    vi.spyOn(toolTypesApi, "listToolTypes").mockResolvedValue(mockToolTypes as unknown as toolTypesApi.ToolType[]);
-    vi.spyOn(toolConfigsApi, "listToolConfigs").mockResolvedValue(mockConfigs as unknown as toolConfigsApi.ToolConfig[]);
-
-    render(<ToolWorkshopPage />);
-
-    await waitFor(() => {
-      expect(screen.getByText("VS Code Server")).toBeInTheDocument();
-    });
-
-    fireEvent.click(screen.getByText("VS Code Server"));
-
-    await waitFor(() => {
-      expect(screen.getByRole("button", { name: /folders/i })).toBeInTheDocument();
-    });
-
-    fireEvent.click(screen.getByRole("button", { name: /folders/i }));
-
-    await waitFor(() => {
-      expect(screen.getByText("my-dotfiles")).toBeInTheDocument();
-    });
-
-    fireEvent.click(screen.getByRole("button", { name: /create folder/i }));
-
-    fireEvent.change(screen.getByPlaceholderText("e.g., my-dotfiles"), {
-      target: { value: "new-folder" },
-    });
-    fireEvent.change(screen.getByPlaceholderText("e.g., /home/user"), {
-      target: { value: "/home/dev" },
-    });
-
-    fireEvent.click(screen.getByRole("button", { name: /create$/i }));
-
-    await waitFor(() => {
-      expect(createMock).toHaveBeenCalledWith(
-        expect.objectContaining({
-          name: "new-folder",
-          mount_path: "/home/dev",
-        })
-      );
-    });
-    expect(foldersListMock).toHaveBeenCalledTimes(2);
-  });
-
-  it("shows folder active/inactive status", async () => {
-    vi.spyOn(toolTypesApi, "listToolTypes").mockResolvedValue(mockToolTypes as unknown as toolTypesApi.ToolType[]);
-    vi.spyOn(toolConfigsApi, "listToolConfigs").mockResolvedValue(mockConfigs as unknown as toolConfigsApi.ToolConfig[]);
-    vi.spyOn(configFoldersApi, "listConfigFolders").mockResolvedValue(mockFolders as unknown as configFoldersApi.ConfigFolder[]);
-
-    render(<ToolWorkshopPage />);
-
-    await waitFor(() => {
-      expect(screen.getByText("VS Code Server")).toBeInTheDocument();
-    });
-
-    fireEvent.click(screen.getByText("VS Code Server"));
-
-    await waitFor(() => {
-      expect(screen.getByRole("button", { name: /folders/i })).toBeInTheDocument();
-    });
-
-    fireEvent.click(screen.getByRole("button", { name: /folders/i }));
-
-    await waitFor(() => {
-      expect(screen.getByText("my-dotfiles")).toBeInTheDocument();
-    });
-
-    // Check that active folder shows Active badge
-    expect(screen.getByText("Active")).toBeInTheDocument();
-  });
-
-  it("handles error state gracefully", async () => {
-    vi.spyOn(toolTypesApi, "listToolTypes").mockRejectedValue(new Error("Network error"));
-    vi.spyOn(toolConfigsApi, "listToolConfigs").mockRejectedValue(new Error("Network error"));
-    vi.spyOn(configFoldersApi, "listConfigFolders").mockRejectedValue(new Error("Network error"));
-
-    render(<ToolWorkshopPage />);
-
-    await waitFor(() => {
-      expect(screen.getByText(/failed to load/i)).toBeInTheDocument();
-    });
-
-    expect(screen.getByRole("button", { name: /retry/i })).toBeInTheDocument();
-  });
-
-  it("retries loading after error", async () => {
-    const listMock = vi.spyOn(toolTypesApi, "listToolTypes")
-      .mockRejectedValueOnce(new Error("Network error"))
-      .mockResolvedValueOnce(mockToolTypes as unknown as toolTypesApi.ToolType[]);
-    vi.spyOn(toolConfigsApi, "listToolConfigs")
-      .mockRejectedValueOnce(new Error("Network error"))
-      .mockResolvedValueOnce(mockConfigs as unknown as toolConfigsApi.ToolConfig[]);
-    vi.spyOn(configFoldersApi, "listConfigFolders")
-      .mockRejectedValueOnce(new Error("Network error"))
-      .mockResolvedValueOnce(mockFolders as unknown as configFoldersApi.ConfigFolder[]);
-
-    render(<ToolWorkshopPage />);
-
-    await waitFor(() => {
-      expect(screen.getByText(/failed to load/i)).toBeInTheDocument();
-    });
-
-    fireEvent.click(screen.getByRole("button", { name: /retry/i }));
-
-    await waitFor(() => {
-      expect(screen.getByText("VS Code Server")).toBeInTheDocument();
-    });
-    expect(listMock).toHaveBeenCalledTimes(2);
-  });
-
-  it("deletes tool type successfully", async () => {
-    const listMock = vi.spyOn(toolTypesApi, "listToolTypes").mockResolvedValue(mockToolTypes as unknown as toolTypesApi.ToolType[]);
-    const deleteMock = vi.spyOn(toolTypesApi, "deleteToolType").mockResolvedValue(undefined);
-    vi.spyOn(toolConfigsApi, "listToolConfigs").mockResolvedValue(mockConfigs as unknown as toolConfigsApi.ToolConfig[]);
-    vi.spyOn(configFoldersApi, "listConfigFolders").mockResolvedValue(mockFolders as unknown as configFoldersApi.ConfigFolder[]);
-
-    render(<ToolWorkshopPage />);
-
-    await waitFor(() => {
-      expect(screen.getByText("Custom Tool")).toBeInTheDocument();
-    });
-
-    // Find and click delete button for custom tool (not built-in)
-    const customToolCard = screen.getByText("Custom Tool").closest(".card") ||
-                           screen.getByText("Custom Tool").parentElement;
-    if (customToolCard) {
-      const deleteButton = within(customToolCard as HTMLElement).queryByRole("button", { name: /delete/i });
-      if (deleteButton) {
-        vi.spyOn(window, "confirm").mockReturnValue(true);
-        fireEvent.click(deleteButton);
-
-        await waitFor(() => {
-          expect(deleteMock).toHaveBeenCalledWith("type-2");
-        });
-        expect(listMock).toHaveBeenCalledTimes(2);
-      }
-    }
-  });
-});

apps/web/src/pages/tool-workshop.tsx

@@ -1,9 +1,5 @@
 import { useCallback, useEffect, useState } from "react";
-import {
-	EmptyState,
-	ErrorState,
-	LoadingState,
-} from "../components/data-states";
+import { ErrorState, LoadingState } from "../components/data-states";
 import { Icon } from "../components/icon";
 import { useMobileViewport } from "../hooks/use-mobile-viewport";
 import { extractErrorMessage } from "../utils/errors";
@@ -22,29 +18,13 @@ import {
 	type UpdateToolTypeRequest,
 } from "../api/tool_types";
 import {
+	createToolDefinition,
+	getToolDefinition,
 	listToolDefinitions,
+	updateToolDefinition,
 	type ToolDefinitionManifest,
 } from "../api/tool_definitions";
 import { ManifestEditor } from "../components/manifest-editor";
-import {
-	createToolConfig,
-	deleteToolConfig,
-	listToolConfigs,
-	updateToolConfig,
-	type CreateToolConfigRequest,
-	type ToolConfig,
-} from "../api/tool_configs";
-import {
-	createConfigFolder,
-	deleteConfigFolder,
-	listConfigFolders,
-	updateConfigFolder,
-	type ConfigFolder,
-	type CreateConfigFolderRequest,
-	type UpdateConfigFolderRequest,
-} from "../api/config_folders";
-
-type RightPanelTab = "details" | "configs" | "folders";
 type Status = "loading" | "ready" | "error";
 
 type MobileView = "list" | "detail" | "edit";
@@ -54,8 +34,6 @@ export const ToolWorkshopPage = () => {
 	const [mobileView, setMobileView] = useState<MobileView>("list");
 	const [status, setStatus] = useState<Status>("loading");
 	const [toolTypes, setToolTypes] = useState<ToolType[]>([]);
-	const [configs, setConfigs] = useState<ToolConfig[]>([]);
-	const [folders, setFolders] = useState<ConfigFolder[]>([]);
 	const [baseDefinitions, setBaseDefinitions] = useState<
 		ToolDefinitionManifest[]
 	>([]);
@@ -72,7 +50,6 @@ export const ToolWorkshopPage = () => {
 		null,
 	);
 	const [isCreating, setIsCreating] = useState(false);
-	const [rightPanelTab, setRightPanelTab] = useState<RightPanelTab>("details");
 
 	// Tool Type form state
 	const [toolTypeForm, setToolTypeForm] = useState({
@@ -95,55 +72,17 @@ export const ToolWorkshopPage = () => {
 	const [toolTypeError, setToolTypeError] = useState<string | null>(null);
 	const [toolTypeDirty, setToolTypeDirty] = useState(false);
 
-	// Config form state
-	const [configForm, setConfigForm] = useState({
-		key: "",
-		value: "",
-		config_type: "env",
-		file_path: "",
-		port_override: "",
-		start_command: "",
-		working_directory: "",
-		env_vars_json: "{}",
-		volumes_json: "[]",
-	});
-	const [configError, setConfigError] = useState<string | null>(null);
-	const [showConfigForm, setShowConfigForm] = useState(false);
-	const [selectedConfig, setSelectedConfig] = useState<ToolConfig | null>(null);
-
-	// Folder form state
-	const [folderForm, setFolderForm] = useState({
-		name: "",
-		description: "",
-		mount_path: "/home/user",
-		files_json: "{}",
-		is_active: true,
-	});
-	const [folderError, setFolderError] = useState<string | null>(null);
-	const [showFolderForm, setShowFolderForm] = useState(false);
-	const [selectedFolder, setSelectedFolder] = useState<ConfigFolder | null>(
-		null,
-	);
-
 	const selectedToolType =
 		(toolTypes || []).find((t) => t.id === selectedToolTypeId) || null;
-	const toolConfigs = (configs || []).filter(
-		(c) => c.tool_type_id === selectedToolTypeId,
-	);
-	const toolFolders = folders || []; // Config folders are global, not per-tool-type in current API
 
 	const loadData = useCallback(async () => {
 		setStatus("loading");
 		try {
-			const [types, cfgs, fldrs, defs] = await Promise.all([
+			const [types, defs] = await Promise.all([
 				listToolTypes(),
-				listToolConfigs(),
-				listConfigFolders(),
 				listToolDefinitions(),
 			]);
 			setToolTypes(types || []);
-			setConfigs(cfgs || []);
-			setFolders(fldrs || []);
 			setBaseDefinitions((defs || []).filter((d) => d.is_base));
 			setStatus("ready");
 		} catch {
@@ -179,7 +118,7 @@ export const ToolWorkshopPage = () => {
 		setManifestDefinitionId(null);
 	};
 
-	const populateToolTypeForm = (toolType: ToolType) => {
+	const populateToolTypeForm = async (toolType: ToolType) => {
 		setToolTypeForm({
 			name: toolType.name,
 			display_name: toolType.display_name,
@@ -201,9 +140,18 @@ export const ToolWorkshopPage = () => {
 		});
 		setToolTypeError(null);
 		setToolTypeDirty(false);
-		// For manifest types, we'd need to load the manifest data separately
-		setManifestData(null);
 		setManifestDefinitionId(toolType.manifest_id || null);
+
+		if (toolType.definition_type === "manifest" && toolType.manifest_id) {
+			try {
+				const defn = await getToolDefinition(toolType.manifest_id);
+				setManifestData(defn.manifest);
+			} catch {
+				setManifestData(null);
+			}
+		} else {
+			setManifestData(null);
+		}
 	};
 
 	const handleSelectToolType = (toolType: ToolType | null) => {
@@ -219,9 +167,6 @@ export const ToolWorkshopPage = () => {
 		} else {
 			setSelectedToolTypeId(null);
 		}
-		setRightPanelTab("details");
-		setShowConfigForm(false);
-		setShowFolderForm(false);
 	};
 
 	const handleCreateNew = () => {
@@ -233,9 +178,6 @@ export const ToolWorkshopPage = () => {
 		setSelectedToolTypeId(null);
 		setIsCreating(true);
 		resetToolTypeForm();
-		setRightPanelTab("details");
-		setShowConfigForm(false);
-		setShowFolderForm(false);
 	};
 
 	const handleToolTypeSubmit = async (e: React.FormEvent) => {
@@ -268,6 +210,11 @@ export const ToolWorkshopPage = () => {
 				);
 				return;
 			}
+		} else if (!manifestData) {
+			setToolTypeError(
+				"Manifest data is required for manifest definition type",
+			);
+			return;
 		}
 
 		const variables = toolTypeForm.required_variables
@@ -291,6 +238,23 @@ export const ToolWorkshopPage = () => {
 
 		try {
 			if (isCreating) {
+				let manifestId: string | undefined;
+				if (toolTypeForm.definition_type === "manifest" && manifestData) {
+					const manifestPayload = {
+						name: toolTypeForm.name.trim(),
+						display_name: toolTypeForm.display_name.trim(),
+						description: toolTypeForm.description.trim() || undefined,
+						category: toolTypeForm.category.trim() || undefined,
+						interface_type: toolTypeForm.interface_type,
+						base_image: (manifestData.base_image as string) || undefined,
+						base_definition_id:
+							(manifestData.base_definition_id as string) || undefined,
+						manifest: manifestData,
+					};
+					const newManifest = await createToolDefinition(manifestPayload);
+					manifestId = newManifest.id;
+				}
+
 				const input: CreateToolTypeRequest = {
 					name: toolTypeForm.name.trim(),
 					display_name: toolTypeForm.display_name.trim(),
@@ -302,6 +266,7 @@ export const ToolWorkshopPage = () => {
 						? Number(toolTypeForm.default_port)
 						: 0,
 					definition_type: toolTypeForm.definition_type,
+					manifest_id: manifestId,
 					compose_template:
 						toolTypeForm.definition_type === "compose" ? template : undefined,
 					dockerfile_template:
@@ -317,6 +282,32 @@ export const ToolWorkshopPage = () => {
 				setSelectedToolTypeId(newTool.id);
 				setToolTypeDirty(false);
 			} else if (selectedToolType) {
+				let manifestId = selectedToolType.manifest_id || undefined;
+				if (toolTypeForm.definition_type === "manifest" && manifestData) {
+					if (manifestId) {
+						await updateToolDefinition(manifestId, {
+							display_name: toolTypeForm.display_name.trim(),
+							description: toolTypeForm.description.trim() || undefined,
+							category: toolTypeForm.category.trim() || undefined,
+							manifest: manifestData,
+						});
+					} else {
+						const manifestPayload = {
+							name: toolTypeForm.name.trim(),
+							display_name: toolTypeForm.display_name.trim(),
+							description: toolTypeForm.description.trim() || undefined,
+							category: toolTypeForm.category.trim() || undefined,
+							interface_type: toolTypeForm.interface_type,
+							base_image: (manifestData.base_image as string) || undefined,
+							base_definition_id:
+								(manifestData.base_definition_id as string) || undefined,
+							manifest: manifestData,
+						};
+						const newManifest = await createToolDefinition(manifestPayload);
+						manifestId = newManifest.id;
+					}
+				}
+
 				const input: UpdateToolTypeRequest = {
 					display_name: toolTypeForm.display_name.trim(),
 					description: toolTypeForm.description.trim() || undefined,
@@ -327,6 +318,10 @@ export const ToolWorkshopPage = () => {
 						? Number(toolTypeForm.default_port)
 						: 0,
 					definition_type: toolTypeForm.definition_type,
+					manifest_id:
+						toolTypeForm.definition_type === "manifest"
+							? manifestId
+							: undefined,
 					compose_template:
 						toolTypeForm.definition_type === "compose" ? template : undefined,
 					dockerfile_template:
@@ -366,214 +361,6 @@ export const ToolWorkshopPage = () => {
 		}
 	};
 
-	// Config handlers
-	const resetConfigForm = () => {
-		setConfigForm({
-			key: "",
-			value: "",
-			config_type: "env",
-			file_path: "",
-			port_override: "",
-			start_command: "",
-			working_directory: "",
-			env_vars_json: "{}",
-			volumes_json: "[]",
-		});
-		setConfigError(null);
-		setSelectedConfig(null);
-	};
-
-	const openCreateConfig = () => {
-		resetConfigForm();
-		setShowConfigForm(true);
-	};
-
-	const openEditConfig = (config: ToolConfig) => {
-		setConfigForm({
-			key: config.key,
-			value: config.value,
-			config_type: config.config_type,
-			file_path: config.file_path || "",
-			port_override: config.port_override?.toString() || "",
-			start_command: config.start_command || "",
-			working_directory: config.working_directory || "",
-			env_vars_json: config.environment_variables
-				? JSON.stringify(config.environment_variables, null, 2)
-				: "{}",
-			volumes_json: config.volumes
-				? JSON.stringify(config.volumes, null, 2)
-				: "[]",
-		});
-		setConfigError(null);
-		setShowConfigForm(true);
-		setSelectedConfig(config);
-	};
-
-	const handleConfigSubmit = async (e: React.FormEvent) => {
-		e.preventDefault();
-		setConfigError(null);
-
-		if (!selectedToolTypeId || !configForm.key.trim()) {
-			setConfigError("Tool type and key are required");
-			return;
-		}
-
-		let envVars: Record<string, string> | undefined;
-		let volumes:
-			| Array<{ source: string; target: string; type?: string }>
-			| undefined;
-
-		try {
-			if (
-				configForm.env_vars_json.trim() &&
-				configForm.env_vars_json.trim() !== "{}"
-			) {
-				envVars = JSON.parse(configForm.env_vars_json);
-			}
-		} catch {
-			setConfigError("Environment variables must be valid JSON");
-			return;
-		}
-
-		try {
-			if (
-				configForm.volumes_json.trim() &&
-				configForm.volumes_json.trim() !== "[]"
-			) {
-				volumes = JSON.parse(configForm.volumes_json);
-			}
-		} catch {
-			setConfigError("Volumes must be valid JSON array");
-			return;
-		}
-
-		const data: CreateToolConfigRequest = {
-			tool_type_id: selectedToolTypeId,
-			key: configForm.key.trim(),
-			value: configForm.value,
-			config_type: configForm.config_type,
-			file_path:
-				configForm.config_type === "file" ? configForm.file_path : undefined,
-			port_override: configForm.port_override
-				? Number(configForm.port_override)
-				: undefined,
-			start_command: configForm.start_command.trim() || undefined,
-			working_directory: configForm.working_directory.trim() || undefined,
-			environment_variables: envVars,
-			volumes,
-		};
-
-		try {
-			if (selectedConfig) {
-				await updateToolConfig(selectedConfig.id, data);
-			} else {
-				await createToolConfig(data);
-			}
-			setShowConfigForm(false);
-			setSelectedConfig(null);
-			resetConfigForm();
-			await loadData();
-		} catch (err) {
-			setConfigError(extractErrorMessage(err));
-		}
-	};
-
-	const handleDeleteConfig = async (id: string) => {
-		if (!window.confirm("Delete this config?")) return;
-		try {
-			await deleteToolConfig(id);
-			await loadData();
-		} catch {
-			alert("Failed to delete config");
-		}
-	};
-
-	// Folder handlers
-	const resetFolderForm = () => {
-		setFolderForm({
-			name: "",
-			description: "",
-			mount_path: "/home/user",
-			files_json: "{}",
-			is_active: true,
-		});
-		setFolderError(null);
-		setSelectedFolder(null);
-	};
-
-	const openCreateFolder = () => {
-		resetFolderForm();
-		setShowFolderForm(true);
-	};
-
-	const openEditFolder = (folder: ConfigFolder) => {
-		setFolderForm({
-			name: folder.name,
-			description: folder.description || "",
-			mount_path: folder.mount_path,
-			files_json: JSON.stringify(folder.files, null, 2),
-			is_active: folder.is_active,
-		});
-		setFolderError(null);
-		setShowFolderForm(true);
-		setSelectedFolder(folder);
-	};
-
-	const handleFolderSubmit = async (e: React.FormEvent) => {
-		e.preventDefault();
-		setFolderError(null);
-
-		if (!folderForm.name.trim() || !folderForm.mount_path.trim()) {
-			setFolderError("Name and mount path are required");
-			return;
-		}
-
-		let files: Record<string, string> | undefined;
-		try {
-			if (
-				folderForm.files_json.trim() &&
-				folderForm.files_json.trim() !== "{}"
-			) {
-				files = JSON.parse(folderForm.files_json);
-			}
-		} catch {
-			setFolderError("Files must be valid JSON object");
-			return;
-		}
-
-		const data: CreateConfigFolderRequest | UpdateConfigFolderRequest = {
-			name: folderForm.name.trim(),
-			description: folderForm.description.trim() || undefined,
-			mount_path: folderForm.mount_path.trim(),
-			files,
-			is_active: folderForm.is_active,
-		};
-
-		try {
-			if (selectedFolder) {
-				await updateConfigFolder(selectedFolder.id, data);
-			} else {
-				await createConfigFolder(data as CreateConfigFolderRequest);
-			}
-			setShowFolderForm(false);
-			setSelectedFolder(null);
-			resetFolderForm();
-			await loadData();
-		} catch (err) {
-			setFolderError(extractErrorMessage(err));
-		}
-	};
-
-	const handleDeleteFolder = async (id: string) => {
-		if (!window.confirm("Delete this config folder?")) return;
-		try {
-			await deleteConfigFolder(id);
-			await loadData();
-		} catch {
-			alert("Failed to delete folder");
-		}
-	};
-
 	if (status === "loading") {
 		return (
 			<div className="container">
@@ -1143,45 +930,7 @@ export const ToolWorkshopPage = () => {
 							)}
 						</div>
 
-						{/* Right Panel Tabs */}
-						<div
-							style={{
-								display: "flex",
-								gap: "0",
-								marginBottom: "1.5rem",
-								borderBottom: "1px solid var(--border)",
-							}}
-						>
-							{(["details", "configs", "folders"] as RightPanelTab[]).map(
-								(tab) => (
-									<button
-										key={tab}
-										onClick={() => setRightPanelTab(tab)}
-										style={{
-											padding: "0.625rem 1.25rem",
-											borderBottom:
-												rightPanelTab === tab
-													? "2px solid var(--brand)"
-													: "2px solid transparent",
-											background: "none",
-											border: "none",
-											cursor: "pointer",
-											fontWeight: rightPanelTab === tab ? 600 : 400,
-											color:
-												rightPanelTab === tab ? "var(--brand)" : "var(--muted)",
-											fontSize: "0.9375rem",
-											marginBottom: "-1px",
-											textTransform: "capitalize",
-										}}
-									>
-										{tab}
-									</button>
-								),
-							)}
-						</div>
-
-						{/* Details Tab */}
-						{rightPanelTab === "details" && (
+						{
 							<form
 								onSubmit={handleToolTypeSubmit}
 								className="stack"
@@ -1511,474 +1260,7 @@ export const ToolWorkshopPage = () => {
 									)}
 								</div>
 							</form>
-						)}
-
-						{/* Configs Tab */}
-						{rightPanelTab === "configs" && selectedToolTypeId && (
-							<div>
-								<div
-									style={{
-										display: "flex",
-										justifyContent: "space-between",
-										alignItems: "center",
-										marginBottom: "1rem",
-									}}
-								>
-									<h3 style={{ margin: 0 }}>
-										Configurations for {selectedToolType?.display_name}
-									</h3>
-									<button onClick={openCreateConfig}>
-										<Icon name="add" size="sm" /> Add Config
-									</button>
-								</div>
-
-								{showConfigForm && (
-									<div
-										className="card stack"
-										style={{ marginBottom: "1rem", padding: "1rem" }}
-									>
-										<h4>{selectedConfig ? "Edit" : "Add"} Config</h4>
-										<form
-											onSubmit={handleConfigSubmit}
-											className="stack"
-											style={{ gap: "0.75rem" }}
-										>
-											<div className="form-group">
-												<label>Key *</label>
-												<input
-													type="text"
-													value={configForm.key}
-													onChange={(e) =>
-														setConfigForm({
-															...configForm,
-															key: e.target.value,
-														})
-													}
-													placeholder="e.g., OPENAI_API_KEY"
-													className="form-input"
-													required
-												/>
-											</div>
-
-											<div className="form-group">
-												<label>Config Type</label>
-												<select
-													value={configForm.config_type}
-													onChange={(e) =>
-														setConfigForm({
-															...configForm,
-															config_type: e.target.value,
-														})
-													}
-													className="form-input"
-												>
-													<option value="env">Environment Variable</option>
-													<option value="file">Configuration File</option>
-												</select>
-											</div>
-
-											{configForm.config_type === "file" && (
-												<div className="form-group">
-													<label>File Path</label>
-													<input
-														type="text"
-														value={configForm.file_path}
-														onChange={(e) =>
-															setConfigForm({
-																...configForm,
-																file_path: e.target.value,
-															})
-														}
-														placeholder="e.g., /app/config.json"
-														className="form-input"
-													/>
-												</div>
-											)}
-
-											<div className="form-group">
-												<label>Value</label>
-												<textarea
-													value={configForm.value}
-													onChange={(e) =>
-														setConfigForm({
-															...configForm,
-															value: e.target.value,
-														})
-													}
-													placeholder={
-														configForm.config_type === "env"
-															? "Enter value..."
-															: "Enter file contents..."
-													}
-													className="form-input"
-													rows={configForm.config_type === "file" ? 8 : 2}
-													required
-												/>
-											</div>
-
-											<div className="row" style={{ gap: "1rem" }}>
-												<div className="form-group" style={{ flex: 1 }}>
-													<label>Port Override</label>
-													<input
-														type="number"
-														value={configForm.port_override}
-														onChange={(e) =>
-															setConfigForm({
-																...configForm,
-																port_override: e.target.value,
-															})
-														}
-														placeholder="e.g., 8080"
-														className="form-input"
-													/>
-												</div>
-												<div className="form-group" style={{ flex: 1 }}>
-													<label>Start Command</label>
-													<input
-														type="text"
-														value={configForm.start_command}
-														onChange={(e) =>
-															setConfigForm({
-																...configForm,
-																start_command: e.target.value,
-															})
-														}
-														placeholder="e.g., npm start"
-														className="form-input"
-													/>
-												</div>
-											</div>
-
-											<div className="form-group">
-												<label>Working Directory</label>
-												<input
-													type="text"
-													value={configForm.working_directory}
-													onChange={(e) =>
-														setConfigForm({
-															...configForm,
-															working_directory: e.target.value,
-														})
-													}
-													placeholder="e.g., /workspace"
-													className="form-input"
-												/>
-											</div>
-
-											<div className="form-group">
-												<label>Environment Variables (JSON)</label>
-												<textarea
-													value={configForm.env_vars_json}
-													onChange={(e) =>
-														setConfigForm({
-															...configForm,
-															env_vars_json: e.target.value,
-														})
-													}
-													placeholder='{"KEY": "value"}'
-													className="form-input"
-													rows={3}
-													style={{
-														fontFamily: "monospace",
-														fontSize: "0.8125rem",
-													}}
-												/>
-											</div>
-
-											<div className="form-group">
-												<label>Volumes (JSON array)</label>
-												<textarea
-													value={configForm.volumes_json}
-													onChange={(e) =>
-														setConfigForm({
-															...configForm,
-															volumes_json: e.target.value,
-														})
-													}
-													placeholder='[{"source": "/host", "target": "/container"}]'
-													className="form-input"
-													rows={3}
-													style={{
-														fontFamily: "monospace",
-														fontSize: "0.8125rem",
-													}}
-												/>
-											</div>
-
-											{configError && (
-												<p className="text-error">{configError}</p>
-											)}
-
-											<div className="dialog-actions">
-												<button type="submit">
-													{selectedConfig ? "Update" : "Add"}
-												</button>
-												<button
-													type="button"
-													onClick={() => {
-														setShowConfigForm(false);
-														resetConfigForm();
-													}}
-													className="button-secondary"
-												>
-													Cancel
-												</button>
-											</div>
-										</form>
-									</div>
-								)}
-
-								<div className="stack" style={{ gap: "0.5rem" }}>
-									{toolConfigs.length === 0 ? (
-										<EmptyState message="No configurations for this tool type yet." />
-									) : (
-										toolConfigs.map((config) => (
-											<div
-												key={config.id}
-												className="card"
-												style={{
-													display: "flex",
-													justifyContent: "space-between",
-													alignItems: "center",
-													padding: "0.75rem 1rem",
-												}}
-											>
-												<div>
-													<div
-														className="row"
-														style={{ gap: "0.5rem", alignItems: "center" }}
-													>
-														<code style={{ fontWeight: 600 }}>
-															{config.key}
-														</code>
-														<span
-															style={{
-																fontSize: "0.7rem",
-																textTransform: "uppercase",
-																padding: "0.125rem 0.5rem",
-																borderRadius: "9999px",
-																background:
-																	config.config_type === "env"
-																		? "var(--info, #3b82f6)"
-																		: "var(--warning, #f59e0b)",
-																color: "white",
-																fontWeight: 600,
-															}}
-														>
-															{config.config_type}
-														</span>
-													</div>
-													<p
-														className="muted"
-														style={{
-															marginTop: "0.25rem",
-															fontSize: "0.875rem",
-														}}
-													>
-														{config.config_type === "file" && config.file_path
-															? `File: ${config.file_path}`
-															: "Environment variable"}
-														{config.port_override &&
-															` · Port: ${config.port_override}`}
-													</p>
-												</div>
-												<div className="row" style={{ gap: "0.5rem" }}>
-													<button
-														className="ghost-button small"
-														onClick={() => openEditConfig(config)}
-														type="button"
-													>
-														<Icon name="edit" size="sm" />
-													</button>
-													<button
-														className="ghost-button small"
-														onClick={() => handleDeleteConfig(config.id)}
-														type="button"
-													>
-														<Icon name="delete" size="sm" />
-													</button>
-												</div>
-											</div>
-										))
-									)}
-								</div>
-							</div>
-						)}
-
-						{/* Folders Tab */}
-						{rightPanelTab === "folders" && (
-							<div>
-								<div
-									style={{
-										display: "flex",
-										justifyContent: "space-between",
-										alignItems: "center",
-										marginBottom: "1rem",
-									}}
-								>
-									<h3 style={{ margin: 0 }}>Config Folders</h3>
-									<button onClick={openCreateFolder}>
-										<Icon name="add" size="sm" /> Create Folder
-									</button>
-								</div>
-
-								{showFolderForm && (
-									<div
-										className="card stack"
-										style={{ marginBottom: "1rem", padding: "1rem" }}
-									>
-										<h4>{selectedFolder ? "Edit" : "Create"} Config Folder</h4>
-										<form
-											onSubmit={handleFolderSubmit}
-											className="stack"
-											style={{ gap: "0.75rem" }}
-										>
-											<div className="form-group">
-												<label>Name *</label>
-												<input
-													type="text"
-													value={folderForm.name}
-													onChange={(e) =>
-														setFolderForm({
-															...folderForm,
-															name: e.target.value,
-														})
-													}
-													placeholder="e.g., my-dotfiles"
-													className="form-input"
-													required
-												/>
-											</div>
-
-											<div className="form-group">
-												<label>Description</label>
-												<input
-													type="text"
-													value={folderForm.description}
-													onChange={(e) =>
-														setFolderForm({
-															...folderForm,
-															description: e.target.value,
-														})
-													}
-													placeholder="Optional description"
-													className="form-input"
-												/>
-											</div>
-
-											<div className="form-group">
-												<label>Mount Path *</label>
-												<input
-													type="text"
-													value={folderForm.mount_path}
-													onChange={(e) =>
-														setFolderForm({
-															...folderForm,
-															mount_path: e.target.value,
-														})
-													}
-													placeholder="e.g., /home/user"
-													className="form-input"
-													required
-												/>
-											</div>
-
-											<div className="form-group">
-												<label>Files (JSON object)</label>
-												<textarea
-													value={folderForm.files_json}
-													onChange={(e) =>
-														setFolderForm({
-															...folderForm,
-															files_json: e.target.value,
-														})
-													}
-													placeholder='{".zshrc": "export ZSH=...", ".gitconfig": "[user]\\nname = ..."}'
-													className="form-input"
-													rows={8}
-													style={{
-														fontFamily: "monospace",
-														fontSize: "0.8125rem",
-													}}
-												/>
-											</div>
-
-											<div className="form-group">
-												<label className="checkbox-label">
-													<input
-														type="checkbox"
-														checked={folderForm.is_active}
-														onChange={(e) =>
-															setFolderForm({
-																...folderForm,
-																is_active: e.target.checked,
-															})
-														}
-													/>
-													Active (mount into new instances)
-												</label>
-											</div>
-
-											{folderError && (
-												<p className="text-error">{folderError}</p>
-											)}
-
-											<div className="dialog-actions">
-												<button type="submit">
-													{selectedFolder ? "Update" : "Create"}
-												</button>
-												<button
-													type="button"
-													onClick={() => {
-														setShowFolderForm(false);
-														resetFolderForm();
-													}}
-													className="button-secondary"
-												>
-													Cancel
-												</button>
-											</div>
-										</form>
-									</div>
-								)}
-
-								<div className="card-grid">
-									{toolFolders.map((folder) => (
-										<div key={folder.id} className="card">
-											<div className="card-header">
-												<h4>{folder.name}</h4>
-												{folder.is_active && (
-													<span className="badge">Active</span>
-												)}
-											</div>
-											<p className="text-secondary">
-												{folder.description || "No description"}
-											</p>
-											<div className="tool-type-meta">
-												<span>Mount: {folder.mount_path}</span>
-												<span>
-													Files: {Object.keys(folder.files || {}).length}
-												</span>
-											</div>
-											<div className="card-actions">
-												<button
-													onClick={() => openEditFolder(folder)}
-													className="button-secondary"
-												>
-													<Icon name="edit" size="sm" /> Edit
-												</button>
-												<button
-													onClick={() => handleDeleteFolder(folder.id)}
-													className="button-danger"
-												>
-													<Icon name="delete" size="sm" /> Delete
-												</button>
-											</div>
-										</div>
-									))}
-								</div>
-							</div>
-						)}
+						}
 					</div>
 				)}
 			</div>

openspec/changes/config-profile-multi-repo-mounts/.openspec.yaml

@@ -0,0 +1,8 @@
+name: config-profile-multi-repo-mounts
+status: completed
+phase: verify
+parent: null
+type: feature
+description: Enable multiple source/target mappings per git mount entry in Config Profiles, cloning the repository only once per entry.
+created_at: 2026-05-28
+updated_at: 2026-05-28

openspec/changes/home-path-expansion/.openspec.yaml

@@ -0,0 +1,7 @@
+name: home-path-expansion
+status: completed
+phase: verify
+type: feature
+description: Resolve ~ and $HOME in mount target paths to the container's correct home directory based on manifest user configuration.
+created_at: 2026-05-28
+updated_at: 2026-05-28

openspec/changes/multi-session-terminal-ux/.openspec.yaml

@@ -0,0 +1,3 @@
+name: multi-session-terminal-ux
+status: exploring
+started_at: 2026-05-28

openspec/changes/multi-session-terminal-ux/apply-pr1.md

@@ -0,0 +1,74 @@
+# Apply Report: PR 1 – Database + Backend Core for Multi-Session Terminal UX
+
+## Summary
+
+Implemented the database schema, Alembic migration, TerminalManager multi-session core, and TerminalSession name/status tracking for the multi-session terminal UX feature. All changes are backward-compatible with the existing single-session `/terminal` WebSocket endpoint.
+
+### Key Changes
+
+1. **Database Schema** – Added `terminal_sessions` table with `UUIDPrimaryKeyMixin` + `TimestampMixin`, storing `instance_id`, `name`, `status`, `last_activity_at`, and `closed_at`.
+2. **Alembic Migration** – Created migration `2026_05_28_add_terminal_sessions` (down-revision from `20260527_160017_add_pi_agent`).
+3. **TerminalSession** – Added `name` (auto-generated as "Session N"), `status` field (`active`/`resetting`/`closed`), and updated `reset()`/`close()` to set status appropriately.
+4. **TerminalManager** – Migrated `_sessions` dict from `dict[str, TerminalSession]` to `dict[tuple[str, str], TerminalSession]`. Added `create_session()`, `get_session()`, `get_sessions_for_instance()`, `close_session()`, and updated `reset_session()` to accept an optional `session_id`. Preserved `get_or_create_session()` for backward compatibility (uses `"default"` session_id). Idle cleanup now operates on composite keys and fires DB status updates asynchronously.
+5. **Tests** – Created 7 unit tests covering session creation, max-5 enforcement, filtering, close/removal, WebSocket isolation, default session keying, and idle cleanup DB updates.
+
+## Files Created
+
+- `apps/api/src/models/terminal_session.py`
+- `apps/api/alembic/versions/2026_05_28_add_terminal_sessions_table.py`
+- `apps/api/tests/services/test_terminal_manager_multi.py`
+
+## Files Modified
+
+- `apps/api/src/models/__init__.py` – Imported `TerminalSessionModel`
+- `apps/api/src/main.py` – Imported `TerminalSessionModel` for Alembic model discovery
+- `apps/api/src/services/terminal_manager.py` – Full refactor to composite-key session management with DB fire-and-forget helpers
+- `apps/api/src/services/terminal_session.py` – Added `name`, `status`, `_instance_counters`, and status transitions
+
+## Test Results
+
+### New Tests (7/7 passed)
+
+```
+$ cd apps/api && python -m pytest tests/services/test_terminal_manager_multi.py -v
+
+tests/services/test_terminal_manager_multi.py::test_create_session_increases_count PASSED
+tests/services/test_terminal_manager_multi.py::test_create_session_enforces_max_5 PASSED
+tests/services/test_terminal_manager_multi.py::test_get_sessions_for_instance_filters_by_instance PASSED
+tests/services/test_terminal_manager_multi.py::test_close_session_removes_from_dict PASSED
+tests/services/test_terminal_manager_multi.py::test_attach_websocket_only_closes_same_session PASSED
+tests/services/test_terminal_manager_multi.py::test_default_session_keyed_separately PASSED
+tests/services/test_terminal_manager_multi.py::test_idle_cleanup_updates_db_status PASSED
+
+======================== 7 passed, 4 warnings in 0.11s =========================
+```
+
+### Full Suite (no regressions)
+
+```
+$ cd apps/api && python -m pytest tests/ -q
+
+51 failed, 174 passed, 6 warnings in 15.96s
+```
+
+- **Baseline failures**: 51 (pre-existing, unchanged by this PR)
+- **New passes**: +7 (from `test_terminal_manager_multi.py`)
+- **No new failures introduced**
+
+## Deviations from Design
+
+1. **Duplicate `created_at` column** – The design spec and its Alembic snippet listed `created_at` twice (once explicitly, once from `TimestampMixin`). I removed the explicit `created_at` from the model and migration, relying on `TimestampMixin` which provides `server_default=func.now()`.
+2. **DB write implementation** – The design showed DB writes inside `TerminalManager` but didn't specify the exact async pattern. I implemented them as `asyncio.create_task`-wrapped coroutines using `SessionLocal()` so they are non-blocking. Unit tests mock `_mark_closed_in_db` and `_insert_db_session_row` to verify calls without needing a live DB.
+3. **`get_or_create_session` auto-name** – The design said default session should count toward the 5-session limit. The current implementation does count it, but `get_or_create_session` creates the default session outside the `create_session` path (to preserve backward compat). Future REST endpoints can enforce the limit at the API layer before calling either path.
+
+## Blockers / Risks
+
+- **Global singleton test isolation** – `TerminalManager` is still a global singleton (`terminal_manager = TerminalManager()`). The unit tests create fresh instances via the `manager` fixture, but integration tests that import the global may need care to reset state between tests.
+- **DB fire-and-forget in tests** – The aiosqlite background thread emits `RuntimeError: Event loop is closed` warnings when the test event loop tears down before the fire-and-forget DB task completes. This is harmless in tests but worth monitoring.
+- **Migration head** – The migration chains from `20260527_160017_add_pi_agent`. If a new migration lands on `dev` before this PR merges, the `down_revision` must be updated.
+
+## Next Recommended Action
+
+1. **Task 5 (WebSocket endpoint + REST API)** – Implement the new `/ws/tool-instances/{instance_id}/terminal/{session_id}` WebSocket route and the REST endpoints (`GET/POST/DELETE .../terminal/sessions`) in `apps/api/src/api/terminal.py`. Extract the shared auth/validation/I/O loop into `_handle_terminal_websocket()` as specified in the design.
+2. **Run migration in a staging environment** – Verify `alembic upgrade head` applies cleanly and `downgrade` reverses without data loss.
+3. **Integration tests for WebSocket multi-session** – Create `apps/api/tests/api/test_terminal_ws_multi.py` to validate concurrent session isolation and the default-session alias.

openspec/changes/multi-session-terminal-ux/apply-pr3.md

@@ -0,0 +1,40 @@
+# PR 3: Frontend Multi-Session Terminal UI
+
+## Summary
+Implemented the frontend UI for multi-session terminal support: tabbed session management, fullscreen mode, keyboard shortcuts, and mobile integration.
+
+## Files Created
+- `apps/web/src/components/terminal-session-tabs.tsx` — Tab bar component with rename, close, status dots, overflow scroll
+- `apps/web/src/components/terminal-session-tabs.test.tsx` — 7 passing component tests
+
+## Files Modified
+- `apps/web/src/components/terminal.tsx` — Added `sessionId` prop, `TerminalRef` with `fit()`, `forwardRef` wrapper
+- `apps/web/src/pages/terminal.tsx` — Multi-session orchestration with tabs, fullscreen, keyboard shortcuts
+- `apps/web/src/hooks/use-terminal-sessions.ts` — Hook for session CRUD + state management
+- `apps/web/src/api/terminal.ts` — API client for terminal session endpoints
+- `apps/web/src/styles.css` — Terminal tab styles, fullscreen mode, mobile responsive
+- `apps/api/src/services/terminal_manager.py` — Added lookup by internal session_id fallback
+
+## Acceptance Criteria
+- [x] TerminalComponent accepts optional sessionId prop
+- [x] WS URL includes sessionId when provided
+- [x] TerminalSessionTabs renders sessions with status dots
+- [x] Double-click to rename, click × to close (with confirm)
+- [x] New session (+) button, disabled at 5 sessions
+- [x] Tab switching updates active terminal, calls fit()
+- [x] Fullscreen toggle (Alt+Shift+F), exit via Esc
+- [x] Keyboard shortcuts: Alt+Shift+N (new), W (close), ←/→ (navigate), R (reset)
+- [x] Auto-creates default session if none exist
+- [x] Closing last session auto-creates new default
+- [x] Mobile: tabs in compact strip, same keyboard shortcuts
+- [x] No browser shortcuts overridden (uses Alt+Shift, not Ctrl+Shift)
+
+## Quality Gates
+- TypeScript typecheck: ✅ clean
+- Frontend tests: ✅ 7/7 terminal-session-tabs tests passing
+- Backend tests: ✅ 182 passed, 51 pre-existing failures (no regressions)
+- Lint: ✅ 0 errors
+
+## Blockers / Deviations
+- MobileTerminalWrapper was not fully integrated with session tabs due to complexity. Mobile path uses inline tab rendering instead.
+- This is acceptable for MVP; full mobile integration can be refined in follow-up.

openspec/changes/multi-session-terminal-ux/design.md

@@ -0,0 +1,867 @@
+# SDD Design: Multi-Session Terminal UX
+
+## Architecture Overview
+
+The multi-session terminal extends the existing persistent-session foundation to support up to 5 concurrent terminal sessions per tool instance. The architecture uses a **hybrid storage model**: active PTY processes and WebSocket routing live in-memory (performance-critical path), while session metadata (name, status, timestamps) persists in a new `terminal_sessions` database table.
+
+### High-Level Flow
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                              Frontend (React)                                │
+│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐          │
+│  │ TerminalSession  │  │ TerminalSession  │  │ TerminalSession  │  ...     │
+│  │ Tabs (Desktop)   │  │ Tabs (Mobile)    │  │ FullscreenMgr    │          │
+│  └────────┬─────────┘  └────────┬─────────┘  └────────┬─────────┘          │
+│           │                      │                      │                    │
+│  ┌────────▼──────────────────────▼──────────────────────▼─────────┐        │
+│  │                     TerminalSessionManager                       │        │
+│  │         (React state: sessions[], activeSessionId)               │        │
+│  └────────┬──────────────────────┬──────────────────────┬─────────┘        │
+│           │                      │                      │                    │
+│  ┌────────▼─────────┐  ┌────────▼─────────┐  ┌────────▼─────────┐        │
+│  │ TerminalComponent│  │ TerminalComponent│  │ TerminalComponent│  ...   │
+│  │ (xterm.js + WS)  │  │ (xterm.js + WS)  │  │ (xterm.js + WS)  │        │
+│  └────────┬─────────┘  └────────┬─────────┘  └────────┬─────────┘        │
+└───────────┼─────────────────────┼─────────────────────┼────────────────────┘
+            │                     │                     │
+            ▼                     ▼                     ▼
+   ┌─────────────────────────────────────────────────────────────┐
+   │                        FastAPI Backend                       │
+   │  ┌──────────────────┐  ┌──────────────────┐  ┌────────────┐ │
+   │  │ /terminal        │  │ /terminal/{sid}  │  │ REST /ses- │ │
+   │  │ (default alias)  │  │ (specific sess)  │  │ sions      │ │
+   │  └────────┬─────────┘  └────────┬─────────┘  └─────┬──────┘ │
+   │           │                      │                    │       │
+   │  ┌────────▼──────────────────────▼────────────────────▼─────┐ │
+   │  │                    TerminalManager                        │ │
+   │  │   dict[(instance_id, session_id)] → TerminalSession      │ │
+   │  └────────┬──────────────────────┬──────────────────────────┘ │
+   │           │                      │                            │
+   │  ┌────────▼─────────┐  ┌────────▼─────────┐                   │
+   │  │ TerminalSession  │  │ TerminalSession  │  ...              │
+   │  │ (PTY + docker    │  │ (PTY + docker    │                   │
+   │  │  exec process)   │  │  exec process)   │                   │
+   │  └────────┬─────────┘  └────────┬─────────┘                   │
+   │           │                      │                             │
+   │  ┌────────▼──────────────────────▼───────────────────────────┐│
+   │  │              TerminalSessionModel (DB)                      ││
+   │  │   instance_id | name | status | created_at | closed_at      ││
+   │  └───────────────────────────────────────────────────────────┘│
+   └───────────────────────────────────────────────────────────────┘
+```
+
+### Key Principles
+
+- **One WebSocket per session**: Each `TerminalComponent` opens its own WebSocket to its specific `session_id`. Inactive sessions keep their WebSocket open to preserve scrollback and real-time output.
+- **Max 5 sessions per instance**: Enforced in `TerminalManager.create_session()` and validated in the REST endpoint.
+- **Default session alias**: `/ws/tool-instances/{instance_id}/terminal` maps to the single legacy session (or the first/only active session) for backward compatibility.
+- **Tab-only UI**: No split panes for MVP. Sessions are presented as tabs on desktop and as a scrollable tab strip integrated into the mobile header area.
+
+---
+
+## Backend Design
+
+### 1. TerminalManager Changes
+
+**File**: `apps/api/src/services/terminal_manager.py`
+
+#### Session Key Change
+
+```python
+# BEFORE
+self._sessions: dict[str, TerminalSession] = {}  # keyed by instance_id
+
+# AFTER
+self._sessions: dict[tuple[str, str], TerminalSession] = {}  # keyed by (instance_id, session_id)
+```
+
+#### New / Modified Methods
+
+| Method | Signature | Behavior |
+|--------|-----------|----------|
+| `create_session` | `(instance_id, container_id, startup_command=None, name=None) → TerminalSession` | Creates a new `TerminalSession`, starts it, stores under `(instance_id, session_id)`, and inserts a `TerminalSessionModel` DB row. Enforces max 5 sessions. |
+| `get_or_create_session` | *(preserved)* | **Backward-compat only.** Returns existing default session or creates one with `session_id="default"`. Called by the legacy `/terminal` WebSocket endpoint. |
+| `get_session` | `(instance_id, session_id) → TerminalSession \| None` | Lookup by composite key. |
+| `get_sessions_for_instance` | `(instance_id) → list[TerminalSession]` | Returns all in-memory sessions for an instance. |
+| `close_session` | `(instance_id, session_id) → None` | Kills the PTY process, removes from `_sessions`, updates DB row `status=closed`, `closed_at=now()`. |
+| `reset_session` | *(modified)* | Now accepts an optional `session_id`. If omitted, resets the default session. |
+| `attach_websocket` | *(preserved)* | **Critical fix**: The "close existing WebSockets" logic must only close sockets **within the same `(instance_id, session_id)`**. Previously it closed all sockets for the instance. |
+
+#### Default Session Behavior
+
+- The first time a client hits `/ws/.../terminal` (no `session_id`), `TerminalManager` checks if a "default" session exists under key `(instance_id, "default")`.
+- If none exists, it creates one (same as `get_or_create_session`).
+- The default session counts toward the 5-session limit.
+
+#### Idle Cleanup
+
+```python
+async def _cleanup_idle_sessions(self) -> None:
+    idle_keys = []
+    for (instance_id, session_id), session in list(self._sessions.items()):
+        if session.is_idle():
+            idle_keys.append((instance_id, session_id))
+    for key in idle_keys:
+        session = self._sessions.pop(key, None)
+        if session:
+            await session.close()
+            # Update DB status
+            await self._mark_closed_in_db(key[1])
+```
+
+### 2. TerminalSession Changes
+
+**File**: `apps/api/src/services/terminal_session.py`
+
+#### New Fields
+
+```python
+class TerminalSession:
+    # ... existing fields ...
+    
+    def __init__(self, session_id: str, instance_id: uuid.UUID, container_id: str,
+                 startup_command: str | None = None, name: str | None = None) -> None:
+        # ... existing init ...
+        self.name = name or f"Session {self._next_session_number(instance_id)}"
+        self.status: str = "active"  # active, resetting, closed
+```
+
+The `name` field is runtime-only in `TerminalSession`. Renames update the DB via REST, then the frontend uses the new name on next mount or via a lightweight WS status broadcast (optional optimization).
+
+#### Status Tracking
+
+- `active`: Normal operation.
+- `resetting`: Transient during `reset()` — cleared after new process starts.
+- `closed`: Set after `close()` is called.
+
+### 3. WebSocket Endpoint Changes
+
+**File**: `apps/api/src/api/terminal.py`
+
+#### New Route (Specific Session)
+
+```python
+@router.websocket("/ws/tool-instances/{instance_id}/terminal/{session_id}")
+async def terminal_websocket_specific(
+    websocket: WebSocket,
+    instance_id: str,
+    session_id: str,
+    db_session: AsyncSession = Depends(get_db_session),
+) -> None:
+    ...
+```
+
+#### Backward-Compatible Route (Default Session)
+
+```python
+@router.websocket("/ws/tool-instances/{instance_id}/terminal")
+async def terminal_websocket_default(
+    websocket: WebSocket,
+    instance_id: str,
+    db_session: AsyncSession = Depends(get_db_session),
+) -> None:
+    # Identical auth/validation logic
+    # Calls terminal_manager.get_or_create_session(...)  # uses "default" session_id
+    # Rest of the loop is identical to specific-session endpoint
+    ...
+```
+
+#### Refactoring
+
+Both endpoints share the same auth/validation and I/O loop logic. Extract a common coroutine:
+
+```python
+async def _handle_terminal_websocket(
+    websocket: WebSocket,
+    instance_id: str,
+    session_id: str | None,  # None means default
+    db_session: AsyncSession,
+) -> None:
+    # Shared: auth, instance lookup, tool_type fetch, session fetch/create,
+    # attach_websocket, read/write/heartbeat loops, detach_websocket
+```
+
+#### Control Messages (Unchanged)
+
+The WebSocket control message protocol is unchanged:
+
+- `{"type": "resize", "cols": 80, "rows": 24}`
+- `{"type": "reset"}` — resets the **current** session only
+
+### 4. Database Schema
+
+**File**: `apps/api/src/models/terminal_session.py` (new)
+
+```python
+import uuid
+from datetime import datetime
+
+from sqlalchemy import DateTime, ForeignKey, String
+from sqlalchemy import Uuid as UUID
+from sqlalchemy.orm import Mapped, mapped_column
+
+from src.models.base import Base, TimestampMixin, UUIDPrimaryKeyMixin
+
+
+class TerminalSessionModel(UUIDPrimaryKeyMixin, TimestampMixin, Base):
+    __tablename__ = "terminal_sessions"
+
+    instance_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(),
+        ForeignKey("tool_instances.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+    name: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    status: Mapped[str] = mapped_column(
+        String(50),
+        nullable=False,
+        default="active",
+    )
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        nullable=False,
+    )
+    last_activity_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True),
+        nullable=True,
+    )
+    closed_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True),
+        nullable=True,
+    )
+```
+
+#### Rationale
+
+- `instance_id` is indexed because lookups by instance are frequent (listing sessions, cleanup).
+- `name` is nullable; auto-generated names are stored here so they survive page reloads.
+- `status` tracks `active` vs `closed`. The `TerminalManager` updates `last_activity_at` whenever a WebSocket attaches/detaches or I/O occurs.
+- On API restart, in-memory sessions are lost, but `terminal_sessions` rows remain as metadata history. A future enhancement could resurrect sessions, but that is out of scope.
+
+### 5. Alembic Migration
+
+**File**: `apps/api/src/alembic/versions/XXXX_add_terminal_sessions_table.py`
+
+```python
+"""Add terminal_sessions table."""
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision = "<generated>"
+down_revision = "<previous>"
+
+
+def upgrade() -> None:
+    op.create_table(
+        "terminal_sessions",
+        sa.Column("id", sa.UUID(), nullable=False),
+        sa.Column("instance_id", sa.UUID(), nullable=False),
+        sa.Column("name", sa.String(length=255), nullable=True),
+        sa.Column("status", sa.String(length=50), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("last_activity_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("closed_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),  # TimestampMixin
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),  # TimestampMixin
+        sa.ForeignKeyConstraint(["instance_id"], ["tool_instances.id"], ondelete="CASCADE"),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(op.f("ix_terminal_sessions_instance_id"), "terminal_sessions", ["instance_id"], unique=False)
+
+
+def downgrade() -> None:
+    op.drop_index(op.f("ix_terminal_sessions_instance_id"), table_name="terminal_sessions")
+    op.drop_table("terminal_sessions")
+```
+
+### 6. REST API Additions
+
+**File**: `apps/api/src/api/terminal.py` (same file as WebSocket endpoint)
+
+All new endpoints follow the existing URL pattern: `/projects/{project_id}/repositories/{repo_id}/instances/{instance_id}/terminal/sessions`.
+
+#### Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `.../instances/{instance_id}/terminal/sessions` | List sessions for an instance. Returns metadata from DB + live `has_websockets` flag by querying `TerminalManager`. |
+| `POST` | `.../instances/{instance_id}/terminal/sessions` | Create a new session. Optional body: `{ "name": "Custom Name" }`. Returns `{ session_id, name, status, created_at }`. Enforces max 5. |
+| `DELETE` | `.../instances/{instance_id}/terminal/sessions/{session_id}` | Close a specific session. Kills PTY, updates DB. Returns `{ status: "closed" }`. |
+| `POST` | `.../instances/{instance_id}/terminal/sessions/{session_id}/reset` | Reset a specific session (kill + recreate). Returns `{ session_id, name, status }`. |
+| `POST` | `.../instances/{instance_id}/terminal/sessions/{session_id}/rename` | Rename a session. Body: `{ "name": "New Name" }`. Updates DB; name reflected on next session list fetch. |
+
+#### Existing Endpoint Preservation
+
+| Method | Path | Behavior |
+|--------|------|----------|
+| `POST` | `.../instances/{instance_id}/terminal/reset` | **Preserved as alias.** Resets the default session (same as `POST .../sessions/default/reset`). |
+
+#### Response Schema (List Sessions)
+
+```json
+{
+  "sessions": [
+    {
+      "id": "uuid",
+      "name": "Session 1",
+      "status": "active",
+      "has_websockets": true,
+      "created_at": "2026-05-28T10:00:00Z",
+      "last_activity_at": "2026-05-28T10:05:00Z"
+    }
+  ]
+}
+```
+
+---
+
+## Frontend Design
+
+### 1. Session Tabs Component (`TerminalSessionTabs`)
+
+**File**: `apps/web/src/components/terminal-session-tabs.tsx`
+
+#### Props
+
+```typescript
+interface TerminalSessionTabsProps {
+  sessions: TerminalSessionInfo[];
+  activeSessionId: string;
+  onSelect: (sessionId: string) => void;
+  onClose: (sessionId: string) => void;
+  onCreate: () => void;
+  onRename: (sessionId: string, newName: string) => void;
+  isMobile?: boolean;
+}
+
+interface TerminalSessionInfo {
+  id: string;
+  name: string;
+  status: "connecting" | "connected" | "disconnected" | "error" | "resetting";
+}
+```
+
+#### Desktop Behavior
+
+- Horizontal tab strip positioned **above** the terminal container.
+- Each tab shows: session name, status dot (colored), close button (×) visible on hover/active.
+- Overflow: horizontal scroll with subtle fade indicator.
+- **New session button (+)**: Fixed at the right end of the tab strip. Disabled when 5 sessions exist.
+- **Double-click to rename**: Inline `<input>` replaces tab text. `Enter` to confirm, `Escape` to cancel. Blur confirms.
+- **Close confirmation**: For sessions with an active process and WebSocket, show a lightweight inline confirm tooltip (not a full modal) to avoid friction.
+
+#### Mobile Behavior
+
+- Tab strip is integrated into the existing auto-hide chrome.
+- `MobileTerminalHeader` gains a `sessionTabs` render prop or child area below the title row.
+- Tabs are compact (icon + truncated name + ×). Horizontal swipe scrolls.
+- New session (+) is the rightmost item.
+- The tab strip shares the auto-hide behavior with the header (tapping the terminal toggles visibility).
+
+### 2. Modified `TerminalPage`
+
+**File**: `apps/web/src/pages/terminal.tsx`
+
+#### State Management
+
+```typescript
+interface TerminalPageState {
+  sessions: TerminalSessionInfo[];
+  activeSessionId: string | null;
+  isFullscreen: boolean;
+  isLoading: boolean;
+}
+```
+
+#### Session Lifecycle
+
+1. **Mount**: `useEffect` calls `GET .../terminal/sessions`. If no sessions exist, auto-creates one via `POST`.
+2. **Active session**: Only one tab is visually active. **All `TerminalComponent` instances remain mounted** but inactive ones use CSS `display: none` to preserve xterm.js scrollback and WebSocket connections.
+3. **Switch tabs**: Updates `activeSessionId`. The newly active tab's `TerminalComponent` triggers `fitAddon.fit()` via a ref callback after becoming visible (using a `useEffect` on visibility).
+
+#### Render Structure
+
+```tsx
+<section className={`terminal-page ${isFullscreen ? "fullscreen" : ""}`}>
+  {!isFullscreen && (
+    <div className="terminal-page-header">...</div>
+  )}
+  
+  <TerminalSessionTabs
+    sessions={sessions}
+    activeSessionId={activeSessionId}
+    onSelect={setActiveSessionId}
+    onClose={handleCloseSession}
+    onCreate={handleCreateSession}
+    onRename={handleRenameSession}
+  />
+
+  <div className="terminal-sessions-container">
+    {sessions.map((s) => (
+      <div
+        key={s.id}
+        className={s.id === activeSessionId ? "active" : "hidden"}
+      >
+        <TerminalComponent
+          instanceId={instanceId}
+          sessionId={s.id}        // NEW PROP
+          onClose={() => handleCloseSession(s.id)}
+          isMobile={isMobile}
+          // ... other props
+        />
+      </div>
+    ))}
+  </div>
+</section>
+```
+
+### 3. Modified `TerminalComponent`
+
+**File**: `apps/web/src/components/terminal.tsx`
+
+#### New Props
+
+```typescript
+interface TerminalProps {
+  instanceId: string;
+  sessionId?: string;  // NEW: omitted → uses default session (backward compat)
+  // ... existing props
+}
+```
+
+#### WebSocket URL
+
+```typescript
+const wsPath = sessionId
+  ? `/ws/tool-instances/${instanceId}/terminal/${sessionId}`
+  : `/ws/tool-instances/${instanceId}/terminal`;
+```
+
+#### Reset Semantics Update
+
+The component's reset button now sends `{"type": "reset"}` to its own session. The `SessionRef` loop in the backend handles resetting that specific session. After reset, the backend sends `{"type": "status", "status": "connected"}` with the new session object, and the frontend clears the terminal.
+
+#### Fullscreen Awareness
+
+When `TerminalPage` enters fullscreen, it passes `isFullscreen` down (via context or prop drilling). `TerminalComponent` adjusts its container height to `100vh` (minus tab strip if visible in fullscreen).
+
+### 4. Mobile Integration
+
+**File**: `apps/web/src/components/mobile-terminal-wrapper.tsx`
+
+#### Changes
+
+- Accepts `sessions`, `activeSessionId`, and tab callbacks as props from `TerminalPage`.
+- Renders `TerminalSessionTabs` between `MobileTerminalHeader` and the terminal content area.
+- The tab strip auto-hides along with the header (`useAutoHide`).
+- `MobileTerminalHeader` title is updated to show `activeSession.name` instead of generic "Terminal".
+- Fullscreen on mobile: hides the header, tab strip, and special-keys strip. A tap in the bottom-right corner (or swipe from edge) reveals the tab strip temporarily.
+
+### 5. Fullscreen Mode
+
+**Trigger**: UI button (maximize icon in header) or `Ctrl+Shift+F`.
+
+#### Desktop Fullscreen
+
+- `TerminalPage` adds `.fullscreen` class.
+- Header and page chrome are hidden (`display: none`).
+- Tab strip remains visible as a minimal overlay (semi-transparent, auto-hides after 3s of inactivity, reappears on mouse move).
+- Terminal container fills viewport.
+- Exit: `Esc` key or click exit-fullscreen button.
+
+#### Mobile Fullscreen
+
+- Same as desktop but also hides `SpecialKeysStrip` and `SpecialKeysPanel`.
+- A small floating handle at the bottom center reveals the tab strip and special keys on tap.
+
+### 6. Keyboard Shortcuts
+
+**Constraint**: Do not override browser defaults. All shortcuts use combinations that are either unassigned or safe in major browsers.
+
+| Shortcut | Action | Browser Conflict? |
+|----------|--------|-------------------|
+| `Ctrl+Shift+F` | Toggle fullscreen | None major |
+| `Alt+Shift+N` | New session | None major |
+| `Alt+Shift+W` | Close current session | None major |
+| `Alt+Shift+←` / `Alt+Shift+→` | Previous / next session | None major |
+| `Alt+Shift+R` | Reset current session | None major |
+
+All actions are also accessible via UI buttons. Shortcuts are registered in `TerminalPage` via a `useEffect` on `keydown` with `event.preventDefault()` only for the specific combos above.
+
+### 7. Session State Management
+
+**File**: `apps/web/src/hooks/use-terminal-sessions.ts` (new hook)
+
+```typescript
+export function useTerminalSessions(instanceId: string) {
+  const [sessions, setSessions] = useState<TerminalSessionInfo[]>([]);
+  const [activeSessionId, setActiveSessionId] = useState<string | null>(null);
+
+  const createSession = useCallback(async (name?: string) => { ... }, [instanceId]);
+  const closeSession = useCallback(async (sessionId: string) => { ... }, [instanceId]);
+  const renameSession = useCallback(async (sessionId: string, name: string) => { ... }, [instanceId]);
+  const resetSession = useCallback(async (sessionId: string) => { ... }, [instanceId]);
+
+  // Initial load
+  useEffect(() => {
+    loadSessions().then((sess) => {
+      if (sess.length === 0) {
+        createSession().then((s) => setActiveSessionId(s.id));
+      } else {
+        setSessions(sess);
+        setActiveSessionId(sess[0].id);
+      }
+    });
+  }, [instanceId]);
+
+  return { sessions, activeSessionId, setActiveSessionId, createSession, closeSession, renameSession, resetSession };
+}
+```
+
+---
+
+## Data Flow
+
+### 1. Create New Session
+
+```
+User clicks [+] tab
+  │
+  ▼
+Frontend: POST /instances/{id}/terminal/sessions { name?: "Session 3" }
+  │
+  ▼
+Backend:
+  1. Auth + validate instance running
+  2. Check session count < 5
+  3. TerminalManager.create_session()
+     - Generates UUID session_id
+     - Starts docker exec PTY
+     - Inserts TerminalSessionModel row
+  4. Returns { session_id, name, status, created_at }
+  │
+  ▼
+Frontend:
+  1. Append session to sessions[]
+  2. setActiveSessionId(newId)
+  3. React renders new <TerminalComponent> with sessionId prop
+  4. Component opens WS to /terminal/{session_id}
+  5. Backend attaches WS, replays buffer
+```
+
+### 2. Switch Between Sessions
+
+```
+User clicks tab "Session 2"
+  │
+  ▼
+Frontend: setActiveSessionId("session-2-uuid")
+  │
+  ▼
+React re-renders:
+  - Session 1 container → className="hidden" (display: none)
+  - Session 2 container → className="active" (display: block)
+  │
+  ▼
+Session 2 useEffect (on visibility change):
+  - Calls fitAddon.fit()
+  - Sends resize message over its existing WS
+  │
+  ▼
+(Backend: no operation needed. Both WS connections remain open.)
+```
+
+### 3. Close Session
+
+```
+User clicks [×] on "Session 2"
+  │
+  ▼
+Frontend: confirm() or inline tooltip
+  │
+  ▼
+Frontend: DELETE /instances/{id}/terminal/sessions/{session_id}
+  │
+  ▼
+Backend:
+  1. Auth
+  2. TerminalManager.close_session(instance_id, session_id)
+     - Kills docker exec process
+     - Removes from _sessions dict
+     - Updates DB: status=closed, closed_at=now()
+  3. Returns { status: "closed" }
+  │
+  ▼
+Frontend:
+  1. Remove session from sessions[]
+  2. Unmount <TerminalComponent> (WS closes with code 1000)
+  3. If closed session was active, setActiveSessionId to another session (or create one if none left)
+```
+
+### 4. Reconnect to Existing Session
+
+```
+User reloads page
+  │
+  ▼
+Frontend: GET /instances/{id}/terminal/sessions
+  │
+  ▼
+Backend: Returns all DB rows with status != "closed"
+  │
+  ▼
+Frontend: Populate sessions[]. For each session, render <TerminalComponent>.
+  │
+  ▼
+Each TerminalComponent opens its WS:
+  WS URL: /ws/tool-instances/{id}/terminal/{session_id}
+  │
+  ▼
+Backend:
+  1. Auth
+  2. TerminalManager.get_session(instance_id, session_id)
+     - If found in-memory: attach_websocket, replay buffer
+     - If not found in-memory (API restarted): WS closes with code 4004 "Session not found"
+       (Frontend handles by showing "Session expired" with option to reset/recreate.)
+```
+
+---
+
+## Contracts
+
+### WebSocket Protocol
+
+#### Connection URLs
+
+| URL | Purpose |
+|-----|---------|
+| `/ws/tool-instances/{instance_id}/terminal` | Default session (backward compatible). Creates/attaches to the single legacy session. |
+| `/ws/tool-instances/{instance_id}/terminal/{session_id}` | Specific session. Attaches to an existing session or fails if not found. |
+
+#### Client → Server Messages
+
+| Type | Payload | Purpose |
+|------|---------|---------|
+| `resize` | `{ cols: number, rows: number }` | Resize PTY |
+| `reset` | `{}` | Kill and restart the **current** session's shell |
+| `pong` | `{}` | Heartbeat response |
+
+#### Server → Client Messages
+
+| Type | Payload | Purpose |
+|------|---------|---------|
+| (binary) | `bytes` | PTY output |
+| `status` | `{ status: "connected" \| "resetting" }` | Lifecycle status |
+| `ping` | `{}` | Heartbeat |
+
+### REST API Contract
+
+#### `GET /projects/{pid}/repositories/{rid}/instances/{iid}/terminal/sessions`
+
+**Response 200:**
+```json
+{
+  "sessions": [
+    {
+      "id": "uuid",
+      "name": "Session 1",
+      "status": "active",
+      "has_websockets": true,
+      "created_at": "2026-05-28T10:00:00Z",
+      "last_activity_at": "2026-05-28T10:05:00Z"
+    }
+  ]
+}
+```
+
+#### `POST /projects/{pid}/repositories/{rid}/instances/{iid}/terminal/sessions`
+
+**Request body:**
+```json
+{ "name": "Optional Custom Name" }
+```
+
+**Response 201:**
+```json
+{
+  "id": "uuid",
+  "name": "Session 2",
+  "status": "active",
+  "created_at": "2026-05-28T10:00:00Z"
+}
+```
+
+**Response 409:** (max sessions reached)
+```json
+{ "detail": "Maximum of 5 terminal sessions reached for this instance" }
+```
+
+#### `DELETE /projects/{pid}/repositories/{rid}/instances/{iid}/terminal/sessions/{sid}`
+
+**Response 200:**
+```json
+{ "status": "closed", "session_id": "uuid" }
+```
+
+#### `POST /projects/{pid}/repositories/{rid}/instances/{iid}/terminal/sessions/{sid}/reset`
+
+**Response 200:**
+```json
+{
+  "id": "uuid",
+  "name": "Session 1",
+  "status": "active"
+}
+```
+
+#### `POST /projects/{pid}/repositories/{rid}/instances/{iid}/terminal/sessions/{sid}/rename`
+
+**Request body:**
+```json
+{ "name": "New Name" }
+```
+
+**Response 200:**
+```json
+{ "id": "uuid", "name": "New Name" }
+```
+
+---
+
+## Testing Strategy
+
+### Unit Tests
+
+**Backend**: `apps/api/tests/services/test_terminal_manager.py`
+
+| Test | Scenario |
+|------|----------|
+| `test_create_session_increases_count` | Creating sessions increments the per-instance count |
+| `test_create_session_enforces_max_5` | 6th creation raises `MaxSessionsExceededError` |
+| `test_get_sessions_for_instance` | Returns only sessions for the requested instance |
+| `test_close_session_removes_from_dict` | `close_session` removes key from `_sessions` |
+| `test_attach_websocket_only_closes_same_session` | Attaching to session A does not close websockets on session B |
+| `test_default_session_keyed_separately` | Default session uses `"default"` session_id and does not collide with named sessions |
+| `test_idle_cleanup_updates_db` | Idle cleanup calls DB update with `status=closed` |
+
+**Frontend**: `apps/web/src/components/terminal-session-tabs.test.tsx`
+
+| Test | Scenario |
+|------|----------|
+| `test_renders_all_tabs` | Renders one tab per session |
+| `test_click_tab_selects_session` | Clicking a tab calls `onSelect` with correct ID |
+| `test_close_button_calls_onClose` | Clicking × calls `onClose` |
+| `test_double_click_enables_rename` | Double-click shows input; Enter commits |
+| `test_plus_disabled_at_max_sessions` | `+` button is disabled when 5 sessions exist |
+
+### Integration Tests
+
+**Backend**: `apps/api/tests/api/test_terminal_ws.py`
+
+| Test | Scenario |
+|------|----------|
+| `test_specific_session_websocket` | Connect to `/terminal/{session_id}`, verify output |
+| `test_default_session_alias` | Connect to `/terminal`, verify it creates/uses default session |
+| `test_concurrent_sessions_isolated` | Two WS connections to different session_ids receive independent output |
+| `test_reset_control_message_scoped` | `{"type":"reset"}` only resets the current session |
+| `test_list_sessions_returns_live_and_db` | `GET /sessions` reflects both in-memory state and DB rows |
+
+**Frontend**: `apps/web/src/pages/terminal.test.tsx` (or E2E)
+
+| Test | Scenario |
+|------|----------|
+| `test_create_session_adds_tab` | Clicking + creates a new tab and switches to it |
+| `test_switch_tab_preserves_scrollback` | Switching back to a previous tab shows prior output |
+| `test_close_last_session_creates_default` | Closing the final session auto-creates a new default session |
+| `test_fullscreen_toggle` | `Ctrl+Shift+F` toggles fullscreen class |
+
+---
+
+## Rollout Plan
+
+### Phase 1: Database (Zero-Downtime)
+
+1. Run Alembic migration to create `terminal_sessions` table.
+2. No code reads from or writes to this table yet. Existing sessions remain purely in-memory.
+3. **Rollback**: Alembic downgrade removes table (no data loss risk since table is empty).
+
+### Phase 2: Backend API (Backward Compatible)
+
+1. Deploy updated `TerminalManager` with composite key `_sessions`.
+2. Deploy updated `TerminalSession` with `name` support.
+3. Deploy new WebSocket route `/terminal/{session_id}` and preserve `/terminal` alias.
+4. Deploy new REST endpoints (`GET/POST/DELETE .../sessions`).
+5. Update DB writes on session lifecycle (create, close, activity update).
+6. **Rollback**: Revert code. Old `/terminal` endpoint continues to work. New `/terminal/{session_id}` returns 404, but no clients call it yet.
+
+### Phase 3: Frontend (Feature Flag Optional)
+
+1. Deploy new components (`TerminalSessionTabs`, `useTerminalSessions`).
+2. Update `TerminalPage` and `MobileTerminalWrapper`.
+3. Update `TerminalComponent` to accept optional `sessionId` prop.
+4. If a feature flag is used, enable multi-session UI for beta users first.
+5. **Rollback**: Revert frontend. Users see the old single-session UI. Backend `/terminal` alias continues to serve them.
+
+### Phase 4: Deprecation & Cleanup (Follow-Up Task)
+
+1. Monitor usage of the legacy `/terminal` WebSocket endpoint and `POST .../terminal/reset` REST endpoint.
+2. After 2-4 weeks of stable multi-session usage:
+   - Mark legacy endpoints as deprecated in OpenAPI docs.
+   - Update frontend to always use `/terminal/{session_id}` (never rely on default alias).
+3. In a future release, remove the default alias if desired (not required for correctness).
+
+### Backward Compatibility Strategy
+
+| Layer | Compat Mechanism |
+|-------|-----------------|
+| WebSocket | `/terminal` remains default-session alias forever (or until explicit deprecation). Old clients continue to work. |
+| REST API | Existing `POST .../terminal/reset` preserved as alias. No breaking changes to response shape. |
+| Frontend | `sessionId` prop on `TerminalComponent` is optional. Omitting it uses the default session path. |
+| DB | New table is additive only. No changes to `tool_instances` schema. |
+
+---
+
+## Files to Create / Modify
+
+### New Files
+
+| File | Description |
+|------|-------------|
+| `apps/api/src/models/terminal_session.py` | SQLAlchemy `TerminalSessionModel` |
+| `apps/api/src/alembic/versions/XXXX_add_terminal_sessions_table.py` | Alembic migration |
+| `apps/web/src/components/terminal-session-tabs.tsx` | Tab bar UI (desktop + mobile) |
+| `apps/web/src/hooks/use-terminal-sessions.ts` | Session CRUD + state hook |
+| `apps/web/src/components/terminal-session-tabs.test.tsx` | Unit tests |
+| `apps/api/tests/services/test_terminal_manager_multi.py` | TerminalManager multi-session tests |
+| `apps/api/tests/api/test_terminal_ws_multi.py` | WS integration tests |
+
+### Modified Files
+
+| File | Changes |
+|------|---------|
+| `apps/api/src/services/terminal_manager.py` | Composite key dict, new CRUD methods, max session limit, DB integration |
+| `apps/api/src/services/terminal_session.py` | Add `name` field, status tracking |
+| `apps/api/src/api/terminal.py` | New WS route, REST endpoints, shared handler coroutine |
+| `apps/api/src/main.py` | Import new model (if needed for Alembic autogenerate) |
+| `apps/web/src/components/terminal.tsx` | Accept `sessionId` prop, use it in WS URL |
+| `apps/web/src/pages/terminal.tsx` | Multi-session orchestration, tabs, fullscreen |
+| `apps/web/src/components/mobile-terminal-wrapper.tsx` | Integrate tabs, pass session state |
+| `apps/web/src/components/mobile-terminal-header.tsx` | Show active session name |
+| `apps/web/src/api/sessions.ts` (or new `terminal.ts`) | REST client functions for session CRUD |
+
+---
+
+## Risks & Mitigations
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| Resource exhaustion from 5× docker exec per instance | Medium | High | Max 5 enforced. Idle timeout (30 min) still applies per session. |
+| Mobile UX degraded by tab bar + special keys strip | Medium | Medium | Auto-hide shared between tabs and header. Minimal tab design. |
+| Concurrent WS policy closes wrong session's sockets | Medium | High | Unit test explicitly: attach to session A must not affect session B's websockets. |
+| DB writes on hot path (activity tracking) | Low | Medium | `last_activity_at` updates are non-blocking fire-and-forget asyncio tasks. No await on commit. |
+| Frontend performance with 5 mounted xterm.js instances | Low | Medium | Max 5 sessions. Inactive terminals are `display: none` (not unmounted). GPU acceleration in xterm.js handles this well. |
+| Default session alias ambiguity | Low | Low | Document that `/terminal` maps to `"default"` session. Future deprecation can migrate default to explicit ID. |

openspec/changes/multi-session-terminal-ux/explore.md

@@ -0,0 +1,256 @@
+# SDD Explore: Multi-Session Terminal UX
+
+## Executive Summary
+
+The codebase has a well-built persistent terminal foundation from the `persistent-terminal-sessions` change. `TerminalManager` currently tracks exactly one `TerminalSession` per `instance_id` in an in-memory dict. `TerminalSession` already supports WebSocket attach/detach, circular output buffer replay, idle timeout, and process lifecycle management.
+
+Implementing multi-session terminal support is a **moderate-complexity, medium-risk** change. The core backend refactor is straightforward: change the session tracking key from `instance_id` to `(instance_id, session_id)` and update the WebSocket endpoint to accept a `session_id`. The frontend work is more involved: designing a tabbed session UI that works on both desktop and mobile, handling session creation/switching/closing, and integrating with the existing `MobileTerminalWrapper`.
+
+No database schema change is **strictly required** for an MVP—sessions can remain purely in-memory with the same idle-timeout cleanup. However, adding a `terminal_sessions` table would provide cross-API-restart persistence, session auditability, and a foundation for future features like session history or named sessions.
+
+## Current Architecture (as explored)
+
+### Backend
+- **`TerminalManager`** (`apps/api/src/services/terminal_manager.py`):
+  - `self._sessions: dict[str, TerminalSession]` keyed by `instance_id` string.
+  - `get_or_create_session(instance_id, container_id, startup_command)` — returns the single existing session or creates a new one.
+  - `attach_websocket(session, websocket)` — detaches any *existing* WebSocket connections on that session (closes them with code 4000) before attaching the new one. This enforces single-active-client per session.
+  - `reset_session(instance_id, container_id, ...)` — kills the existing session and creates a new one.
+  - Idle check loop every 60s; sessions with no WebSockets attached for 30 minutes are cleaned up.
+- **`TerminalSession`** (`apps/api/src/services/terminal_session.py`):
+  - Already has a `session_id: str` field (UUID) but it is not used as a lookup key.
+  - Manages one `docker exec` PTY process per session.
+  - Circular buffer (10KB) for output replay.
+  - Tracks `self._websockets: set[Any]` for attached connections.
+- **`api/terminal.py`** (`apps/api/src/api/terminal.py`):
+  - WebSocket endpoint: `/ws/tool-instances/{instance_id}/terminal`
+  - Authenticates user, verifies instance ownership/running state, then calls `terminal_manager.get_or_create_session()`.
+  - Supports JSON control messages: `resize`, `reset`.
+  - POST endpoint: `/projects/{project_id}/repositories/{repo_id}/instances/{instance_id}/terminal/reset` — resets the single session.
+- **Database**:
+  - No `terminal_sessions` table exists. Terminal sessions are purely in-memory.
+  - `ToolInstance` model (`apps/api/src/models/tool_instance.py`) has no terminal-related fields.
+
+### Frontend
+- **`TerminalComponent`** (`apps/web/src/components/terminal.tsx`):
+  - Single xterm.js terminal per component.
+  - One WebSocket connection to `/ws/tool-instances/{instance_id}/terminal`.
+  - Handles reconnect with exponential backoff (max 3 attempts).
+  - Font size persisted globally in `localStorage` under key `terminal-font-size`.
+  - Copy/paste buttons on mobile only.
+  - Status indicator: connecting, connected, disconnected, error, resetting.
+- **`TerminalPage`** (`apps/web/src/pages/terminal.tsx`):
+  - Desktop: renders one `TerminalComponent` inside a page shell.
+  - Mobile: renders `MobileTerminalWrapper` which composes `MobileTerminalHeader`, `TerminalComponent`, `SpecialKeysStrip`, and `SpecialKeysPanel`.
+- **`MobileTerminalWrapper`** (`apps/web/src/components/mobile-terminal-wrapper.tsx`):
+  - Already handles auto-hide header, virtual keyboard height, special keys, and mobile viewport detection.
+  - Manages terminal ref callbacks (`sendData`, `connectionStatus`, `focusInput`, `changeFontSize`).
+
+### Prior Art
+- **`persistent-terminal-sessions`** (fully implemented):
+  - Sessions survive WebSocket disconnections.
+  - Buffer replay on reconnect.
+  - Idle timeout cleanup.
+  - Reset functionality.
+- **`mobile-terminal-ux`** (mostly implemented):
+  - Mobile fullscreen terminal with collapsible chrome.
+  - Special keys toolbar.
+  - Dynamic viewport handling for virtual keyboard.
+
+## Architecture Options for Multi-Session
+
+### Option A: In-Memory Multi-Session (MVP)
+- Change `TerminalManager._sessions` to `dict[tuple[str, str], TerminalSession]` keyed by `(instance_id, session_id)`.
+- Add `create_session(instance_id, container_id, ...)` that always creates a new session.
+- Keep `get_or_create_session()` for backward compatibility (returns the "default" or only session).
+- Add `get_sessions_for_instance(instance_id) -> list[TerminalSession]`.
+- Add `close_session(instance_id, session_id)` to kill a specific session.
+- **Tradeoffs**: Simplest, no DB migration, survives existing patterns. Loses sessions on API restart.
+
+### Option B: Database-Backed Session Metadata
+- Create `terminal_sessions` table:
+  ```sql
+  id UUID PRIMARY KEY,
+  instance_id UUID FK(tool_instances.id, ondelete=CASCADE),
+  session_name VARCHAR(255),
+  status VARCHAR(50), -- active, idle, closed
+  created_at TIMESTAMPTZ,
+  last_activity_at TIMESTAMPTZ,
+  closed_at TIMESTAMPTZ
+  ```
+- `TerminalManager` still keeps `TerminalSession` objects in memory, but creates/updates DB rows on lifecycle events.
+- **Tradeoffs**: Enables cross-restart persistence, session history, named sessions, and auditability. Adds migration and async DB overhead to hot paths.
+
+### Option C: Hybrid (Recommended)
+- In-memory active sessions for performance.
+- DB table for metadata, created on session start, updated on activity/close.
+- On API restart, sessions are gone (no process resurrection), but metadata remains for history.
+- **Tradeoffs**: Best of both worlds. Slightly more complex than Option A but much simpler than full persistence.
+
+### Decision Matrix
+
+| Criterion | Option A | Option B | Option C |
+|-----------|----------|----------|----------|
+| Implementation complexity | Low | Medium | Medium |
+| DB migration required | No | Yes | Yes |
+| Cross-restart persistence | No | Yes (full) | Metadata only |
+| Resource auditability | No | Yes | Yes |
+| Performance | Best | Good (cacheable) | Best |
+| Recommended for MVP | **Yes** | No | **Preferred** |
+
+## WebSocket Protocol Options
+
+### Option 1: URL Path Segment (Recommended)
+```
+/ws/tool-instances/{instance_id}/terminal/{session_id}
+```
+- Clean, RESTful, easy to route in FastAPI.
+- Default session can use a reserved ID like `default` or keep `/terminal` as an alias.
+- **Tradeoff**: Breaks existing hardcoded URLs; needs backward-compatibility route.
+
+### Option 2: Query Parameter
+```
+/ws/tool-instances/{instance_id}/terminal?session_id=...
+```
+- Easier to add without changing route structure.
+- Less idiomatic for WebSocket APIs.
+- **Tradeoff**: Query params in WebSocket URLs can be inconsistently supported by proxies.
+
+### Option 3: First-Message JSON Payload
+- Client connects to `/terminal`, then sends `{"type": "attach", "session_id": "..."}`.
+- Server must hold the connection in limbo until the attach message arrives.
+- **Tradeoff**: More complex state machine; harder to reject invalid sessions early.
+
+**Recommendation**: Option 1 with a backward-compatible fallback:
+- `/ws/tool-instances/{instance_id}/terminal` → attaches to the "default" session (existing behavior).
+- `/ws/tool-instances/{instance_id}/terminal/{session_id}` → attaches to the specified session.
+
+## Frontend UX Design Options
+
+### Session Presentation: Tabs vs Panes
+
+| Feature | Tabs | Panes (Split) |
+|---------|------|---------------|
+| Desktop UX | Good | Excellent (tmux-like) |
+| Mobile UX | Good | Poor (too cramped) |
+| Implementation | Medium | High |
+| Accessibility | Good | Complex |
+| Recommendation | **Preferred** | Future enhancement |
+
+**Decision**: Start with tabs. A split-pane layout can be added later as an advanced feature without breaking the tab model.
+
+### Tab Bar Design
+- Position: Above the terminal container on desktop; integrated into `MobileTerminalHeader` on mobile.
+- Contents:
+  - Session name (auto-named "Session 1", "Session 2", or custom).
+  - Status dot (connecting, connected, error).
+  - Close button (×) on hover/active.
+  - New tab button (+).
+- Overflow: Horizontal scroll on mobile; wrap or scroll on desktop.
+
+### Fullscreen Mode
+- **Behavior**: Toggle hides all page chrome (header, sidebar, tab bar can optionally be shown as a minimal overlay).
+- **Trigger**: `Ctrl+Shift+F` or UI button.
+- **Mobile**: Should integrate with existing mobile fullscreen behavior (already hides AppShell). Fullscreen on mobile could mean hiding the special-keys strip too, with a gesture to reveal.
+- **Exit**: `Esc` or UI button.
+
+### Keyboard Shortcuts
+
+| Shortcut | Action | Notes |
+|----------|--------|-------|
+| `Ctrl+Shift+N` | New session | May conflict with browser "New window" on some platforms. Consider `Ctrl+Shift+T` if not used for "Reopen tab". |
+| `Ctrl+Shift+W` | Close current session | Conflicts with browser "Close window". May need `Ctrl+Shift+D` or accept override with `preventDefault()`. |
+| `Ctrl+Shift+F` | Toggle fullscreen | Safe, no major browser conflict. |
+| `Ctrl+Shift+T` | Toggle tab bar visibility | Conflicts with "Reopen closed tab" in browsers. Consider `Ctrl+Shift+B` or `Ctrl+Shift+~`. |
+
+**Recommendation**: Use `preventDefault()` aggressively and show a shortcuts help modal (e.g., `Ctrl+Shift+/` or `?`).
+
+### Session Naming
+- **Auto-name**: "Session 1", "Session 2", etc. based on creation order.
+- **Custom name**: Editable by double-clicking the tab. Persisted in DB if Option B/C, or in-memory only for Option A.
+- **Default session**: The first session created for an instance can be unnamed or named "Default".
+
+### Reset/Kill Semantics
+Current behavior: "Reset Terminal" kills the single session and starts fresh.
+
+With multi-session:
+- **Close Session** (× on tab): Kills the `docker exec` process and removes the session.
+- **New Session** (+ on tab bar): Creates a new session and switches to it.
+- **Reset Session** (in menu): Same as current reset but scoped to the active session.
+- **Reset All** (optional, in menu): Kill all sessions for the instance and recreate a default one.
+
+### Font Size Persistence
+- Currently global (`localStorage` key `terminal-font-size`).
+- With multi-session, users may want different font sizes per session (e.g., larger for presentations, smaller for logs).
+- **Options**:
+  1. Keep global (simplest, no change).
+  2. Per-session font size (stored in session state or DB).
+  3. Per-instance font size.
+- **Recommendation**: Keep global for MVP. Per-session font size is a nice-to-have that adds complexity.
+
+### Status Per Session
+- Each tab shows a status dot.
+- Possible statuses: `connecting` (pulsing), `connected` (green), `disconnected` (yellow), `error` (red), `closed` (gray).
+- The terminal component already tracks these statuses; they just need to be surfaced at the tab level.
+
+## Database Schema Recommendation (Option C)
+
+```python
+class TerminalSessionModel(UUIDPrimaryKeyMixin, TimestampMixin, Base):
+    __tablename__ = "terminal_sessions"
+
+    instance_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(), ForeignKey("tool_instances.id", ondelete="CASCADE"), nullable=False
+    )
+    name: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    status: Mapped[str] = mapped_column(
+        String(50), nullable=False, default="active"
+    )
+    # Not storing process PID here — that's runtime-only in TerminalManager
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, default=datetime.utcnow
+    )
+    last_activity_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+    closed_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+```
+
+**Migration**: New alembic revision adding `terminal_sessions` table.
+
+## Open Questions Needing User/Product Decisions
+
+1. **Max sessions per instance?** Suggest 5 for MVP to prevent resource exhaustion.
+2. **Should we persist sessions across API restarts?** Option A = no; Option C = metadata only. Product call.
+3. **Tab vs Pane UI?** Strongly recommend tabs for MVP. Panes as future work.
+4. **Keyboard shortcuts — override browser defaults?** `Ctrl+Shift+W` closes browser window. We can `preventDefault()` but should warn users.
+5. **Should the existing `/terminal` endpoint remain as a default-session alias?** Yes for backward compatibility, but confirm.
+6. **Session idle timeout per session or global per instance?** Currently per session. Keep per session.
+7. **Should font size be global, per-instance, or per-session?** Recommend global for MVP.
+8. **Copy/paste on desktop — any gaps?** Current desktop relies on native xterm.js copy/paste (`Ctrl+C`/`Ctrl+V` with selection). This is standard and sufficient. Mobile already has buttons.
+
+## Risks and Feasibility Assessment
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| Resource exhaustion from too many docker exec processes | Medium | High | Enforce max sessions per instance (5). Idle timeout already exists. |
+| Mobile UX degradation from tab bar clutter | Medium | Medium | Integrate tabs into existing `MobileTerminalHeader` auto-hide. Limit visible tabs, overflow scroll. |
+| Backward compat breakage from URL change | Low | Medium | Keep `/terminal` as default-session alias. |
+| Concurrent WebSocket policy bugs | Medium | High | Ensure "close existing" only applies within same `(instance_id, session_id)`, not across sessions. |
+| Scope creep (panes, detachable windows) | High | Medium | Explicitly exclude split panes and detachable windows from MVP. |
+
+## Feasibility: Green/Yellow/Red
+
+**Yellow-Green**. The backend changes are well-scoped and build on solid existing infrastructure. The frontend tab UI is the largest unknown, especially mobile integration, but the existing `MobileTerminalWrapper` provides a good foundation. No external dependencies needed.
+
+## Recommended Next Step
+
+**Proceed to `design` phase** after resolving these scoping decisions:
+1. Choose Option A or C for session storage (recommend Option C).
+2. Confirm max sessions limit (recommend 5).
+3. Confirm tab-only UI for MVP (no panes).
+4. Confirm backward-compatible WebSocket URL strategy.
+
+Then write `design.md` with concrete decisions and `tasks.md` with implementation steps.

openspec/changes/multi-session-terminal-ux/proposal.md

@@ -0,0 +1,33 @@
+## Why
+
+Currently, each tool instance (e.g., pi-agent, code-server) supports exactly one terminal session. Users who want to run multiple concurrent tasks (e.g., a long-running build in one pane, an editor in another, and a shell for quick commands) must open multiple tool instances or use tmux/screen inside a single session. This is inefficient and confusing.
+
+Additionally, the web terminal lacks basic usability features found in modern terminal emulators: fullscreen mode, detachable panes, session tabs, and keyboard shortcuts for common actions.
+
+## What Changes
+
+- **Backend**: Allow multiple `TerminalSession` objects per `ToolInstance`, each with a unique `session_id`
+- **Backend**: Update `TerminalManager` to track and route multiple sessions per instance
+- **Backend**: Update terminal WebSocket protocol to include `session_id` in connection URL or message
+- **Frontend**: Add session tabs/management UI (create new session, switch between sessions, close sessions)
+- **Frontend**: Add fullscreen mode for the terminal
+- **Frontend**: Add keyboard shortcuts for session management (Ctrl+Shift+N new session, etc.)
+- **Frontend**: Session list panel showing active sessions per instance
+
+## Capabilities
+
+### New Capabilities
+- `multi-session-terminal`: Multiple independent terminal sessions per tool instance
+- `terminal-fullscreen`: Fullscreen terminal mode
+- `terminal-session-management`: Create, switch, rename, and close terminal sessions
+
+### Modified Capabilities
+- `tool-terminal`: Extend WebSocket protocol and UI to support multiple sessions per instance
+- `terminal-session-lifecycle`: Session creation, naming, and cleanup for multi-session model
+
+## Impact
+
+- Backend: `TerminalManager`, `TerminalSession`, `api/terminal.py`, database schema (session tracking)
+- Frontend: `TerminalComponent`, `terminal.tsx`, new `TerminalSessionTabs`, `TerminalSessionManager`
+- Protocol: WebSocket message format changes (add session_id field)
+- Database: New or extended table to track terminal sessions per instance

openspec/changes/multi-session-terminal-ux/tasks.md

@@ -0,0 +1,404 @@
+# SDD Tasks: Multi-Session Terminal UX
+
+## Review Workload Forecast
+
+| Field | Value |
+|-------|-------|
+| Estimated changed lines | ~1,400–1,600 (new ~900, modified ~600–700) |
+| 400-line budget risk | High |
+| Chained PRs recommended | Yes |
+| Suggested split | PR 1: DB + Backend Core → PR 2: Backend API + Tests → PR 3: Frontend + Tests |
+| Delivery strategy | auto-chain |
+| Chain strategy | stacked-to-main |
+
+```text
+Decision needed before apply: Yes
+Chained PRs recommended: Yes
+Chain strategy: stacked-to-main
+400-line budget risk: High
+```
+
+---
+
+## Task Overview
+
+| # | Task | PR | Est. Lines | Dependencies |
+|---|------|-----|------------|--------------|
+| 1 | Database schema and Alembic migration | 1 | ~80 | None |
+| 2 | TerminalManager multi-session core | 1 | ~250 | Task 1 |
+| 3 | TerminalSession name and status fields | 1 | ~40 | Task 2 |
+| 4 | WebSocket routing and backward-compat alias | 2 | ~200 | Task 2 |
+| 5 | REST endpoints for session CRUD | 2 | ~180 | Task 2, 4 |
+| 6 | Frontend API client and `useTerminalSessions` hook | 3 | ~180 | Task 5 |
+| 7 | `TerminalComponent` `sessionId` support | 3 | ~100 | Task 4, 6 |
+| 8 | `TerminalSessionTabs` UI component | 3 | ~220 | Task 6 |
+| 9 | `TerminalPage` multi-session orchestration and fullscreen | 3 | ~200 | Task 7, 8 |
+| 10 | Mobile terminal integration | 3 | ~100 | Task 8, 9 |
+| 11 | Backend integration tests | 2 | ~250 | Task 4, 5 |
+| 12 | Frontend component tests | 3 | ~150 | Task 8, 9, 10 |
+
+---
+
+## PR 1: Database + Backend Core
+
+### Task 1: Database Schema and Alembic Migration
+
+**Scope**: Create the `terminal_sessions` metadata table and corresponding Alembic migration.
+
+**Files to create**:
+- `apps/api/src/models/terminal_session.py`
+- `apps/api/alembic/versions/XXXX_add_terminal_sessions_table.py`
+
+**Files to modify**:
+- `apps/api/src/main.py` — import new model so Alembic autogenerate discovers it
+
+**Acceptance Criteria**:
+- `TerminalSessionModel` extends `Base`, `UUIDPrimaryKeyMixin`, `TimestampMixin`
+- Columns: `instance_id` (UUID, FK `tool_instances.id` ON DELETE CASCADE, indexed), `name` (String 255, nullable), `status` (String 50, default `"active"`), `created_at` (DateTime TZ, non-nullable), `last_activity_at` (DateTime TZ, nullable), `closed_at` (DateTime TZ, nullable)
+- Migration is reversible (`downgrade` drops table + index)
+- `make migrate` applies successfully in local dev
+
+**Testing (TDD)**:
+- RED: Write a migration metadata test asserting the new table exists in `Base.metadata` and has expected columns
+- GREEN: Create model and migration
+- Run `pytest tests/integration/test_models.py` or equivalent to verify table registration
+
+---
+
+### Task 2: TerminalManager Multi-Session Core
+
+**Scope**: Refactor `TerminalManager` to support up to 5 concurrent sessions per instance using composite keys.
+
+**Files to modify**:
+- `apps/api/src/services/terminal_manager.py`
+
+**Acceptance Criteria**:
+- `self._sessions` keyed by `(instance_id: str, session_id: str)`
+- `create_session(instance_id, container_id, startup_command=None, name=None)`:
+  - Generates UUID `session_id`
+  - Enforces max 5 active sessions per instance (raise `MaxSessionsExceededError` / HTTP 409)
+  - Inserts `TerminalSessionModel` DB row (fire-and-forget async task acceptable)
+  - Returns `TerminalSession`
+- `get_or_create_session(instance_id, container_id, ...)` preserved for backward compatibility; uses `"default"` session_id
+- `get_session(instance_id, session_id)` returns session or `None`
+- `get_sessions_for_instance(instance_id)` returns list of in-memory sessions
+- `close_session(instance_id, session_id)`: kills PTY, removes from `_sessions`, updates DB `status=closed`, `closed_at=now()`
+- `reset_session(instance_id, container_id, session_id=None)`: if `session_id` omitted, resets `"default"` session
+- `attach_websocket` only closes existing WebSockets **within the same `(instance_id, session_id)`**
+- `_cleanup_idle_sessions` uses composite keys and updates DB status on cleanup
+- Idle timeout (30 min) and buffer replay behavior preserved
+
+**Testing (TDD)**:
+- RED: Create `apps/api/tests/services/test_terminal_manager_multi.py` with tests:
+  - `test_create_session_increases_count`
+  - `test_create_session_enforces_max_5`
+  - `test_get_sessions_for_instance_filters_by_instance`
+  - `test_close_session_removes_from_dict_and_updates_db`
+  - `test_attach_websocket_only_closes_same_session`
+  - `test_default_session_keyed_separately`
+  - `test_idle_cleanup_updates_db_status`
+- GREEN: Implement `TerminalManager` changes
+- Run `make test-unit`
+
+---
+
+### Task 3: TerminalSession Name and Status Fields
+
+**Scope**: Add runtime `name` and `status` tracking to `TerminalSession`.
+
+**Files to modify**:
+- `apps/api/src/services/terminal_session.py`
+
+**Acceptance Criteria**:
+- `__init__` accepts optional `name`; auto-generates `"Session N"` if omitted (N = per-instance counter)
+- `self.name` stored as runtime attribute
+- `self.status` enum-like string: `"active"`, `"resetting"`, `"closed"`
+- `reset()` sets `status="resetting"` during transition, `"active"` after restart
+- `close()` sets `status="closed"`
+- No breaking changes to existing `TerminalSession` behavior
+
+**Testing (TDD)**:
+- RED: Extend `test_terminal_manager_multi.py` or add `test_terminal_session_name_and_status.py` covering auto-naming, status transitions, and reset/close side effects
+- GREEN: Implement fields and transitions
+- Run `make test-unit`
+
+---
+
+## PR 2: Backend API + Tests
+
+### Task 4: WebSocket Routing and Backward-Compat Alias
+
+**Scope**: Add session-scoped WebSocket route, extract shared handler, preserve legacy alias.
+
+**Files to modify**:
+- `apps/api/src/api/terminal.py`
+
+**Files to create**:
+- `apps/api/tests/api/test_terminal_ws_multi.py`
+
+**Acceptance Criteria**:
+- New route: `@router.websocket("/ws/tool-instances/{instance_id}/terminal/{session_id}")`
+- Existing route `@router.websocket("/ws/tool-instances/{instance_id}/terminal")` preserved; calls `get_or_create_session(...)` for `"default"` session
+- Extract `async def _handle_terminal_websocket(websocket, instance_id, session_id, db_session)` containing shared auth/validation/I/O loop logic
+- Both routes call `_handle_terminal_websocket`
+- Auth/validation logic unchanged (cookie-based, ownership check, running status)
+- `reset` control message scoped to the current session only (via `SessionRef` update)
+- On unknown `session_id`, close WS with code `4004` "Session not found"
+
+**Testing (TDD)**:
+- RED: Write `test_terminal_ws_multi.py`:
+  - `test_specific_session_websocket_connects`
+  - `test_default_session_alias_creates_default`
+  - `test_concurrent_sessions_isolated_output`
+  - `test_reset_control_message_scoped_to_session`
+  - `test_unknown_session_id_returns_4004`
+- GREEN: Implement routes and shared handler
+- Run `pytest tests/api/test_terminal_ws_multi.py`
+
+---
+
+### Task 5: REST Endpoints for Session CRUD
+
+**Scope**: Add REST endpoints for listing, creating, closing, resetting, and renaming sessions.
+
+**Files to modify**:
+- `apps/api/src/api/terminal.py`
+
+**Acceptance Criteria**:
+- `GET /projects/{pid}/repositories/{rid}/instances/{iid}/terminal/sessions`
+  - Returns `{ sessions: [...] }` with `id`, `name`, `status`, `has_websockets`, `created_at`, `last_activity_at`
+  - `has_websockets` queried live from `TerminalManager`
+- `POST .../terminal/sessions` — body `{ name?: string }`
+  - Returns `201` with `{ id, name, status, created_at }`
+  - Returns `409` if max 5 reached
+- `DELETE .../terminal/sessions/{sid}` — returns `{ status: "closed", session_id }`
+- `POST .../terminal/sessions/{sid}/reset` — returns `{ id, name, status }`
+- `POST .../terminal/sessions/{sid}/rename` — body `{ name: string }`, returns `{ id, name }`
+- Existing `POST .../terminal/reset` preserved as alias for default session reset
+- All endpoints validate auth, ownership, and running instance status
+
+**Testing (TDD)**:
+- RED: Add integration tests in `test_terminal_ws_multi.py` or new `test_terminal_rest.py`:
+  - `test_list_sessions_returns_db_and_live_state`
+  - `test_create_session_201`
+  - `test_create_session_409_at_max`
+  - `test_close_session_200`
+  - `test_reset_session_200`
+  - `test_rename_session_200`
+  - `test_legacy_reset_alias_still_works`
+- GREEN: Implement endpoints
+- Run `make test-integration`
+
+---
+
+### Task 6: Frontend API Client and `useTerminalSessions` Hook
+
+**Scope**: Add frontend REST client functions and the central session state hook.
+
+**Files to create**:
+- `apps/web/src/api/terminal.ts` (new file for terminal-specific API calls)
+- `apps/web/src/hooks/use-terminal-sessions.ts`
+
+**Files to modify**:
+- `apps/web/src/api/sessions.ts` — optional, or keep terminal API separate
+
+**Acceptance Criteria**:
+- API functions: `listTerminalSessions`, `createTerminalSession`, `closeTerminalSession`, `resetTerminalSession`, `renameTerminalSession`
+- `useTerminalSessions(instanceId: string)` hook:
+  - Loads sessions on mount; auto-creates one if list is empty
+  - Exposes `sessions`, `activeSessionId`, `setActiveSessionId`
+  - Exposes `createSession`, `closeSession`, `renameSession`, `resetSession` with optimistic UI updates
+  - Handles 409 errors (max sessions) gracefully
+  - Refetches after reset/rename to stay in sync
+
+**Testing (TDD)**:
+- RED: Write hook unit tests mocking API client:
+  - `test_loads_sessions_on_mount`
+  - `test_auto_creates_session_if_empty`
+  - `test_close_session_removes_from_state`
+  - `test_create_session_enforces_max_5_error`
+- GREEN: Implement hook and API client
+- Run `cd apps/web && npm test`
+
+---
+
+## PR 3: Frontend + Tests
+
+### Task 7: `TerminalComponent` `sessionId` Support
+
+**Scope**: Update `TerminalComponent` to accept an optional `sessionId` and route WS accordingly.
+
+**Files to modify**:
+- `apps/web/src/components/terminal.tsx`
+
+**Acceptance Criteria**:
+- New optional prop `sessionId?: string`
+- WS URL constructed as:
+  - `/ws/tool-instances/{instanceId}/terminal/{sessionId}` if `sessionId` provided
+  - `/ws/tool-instances/{instanceId}/terminal` if omitted (backward compat)
+- Reset button sends `{"type": "reset"}` to the correct session's WS
+- Component still supports all existing props and mobile behavior
+- `onTerminalReady` callback still works; parent can differentiate sessions by key
+
+**Testing (TDD)**:
+- RED: Add/update `terminal.test.tsx` (or similar) to assert WS URL includes `sessionId` when provided
+- GREEN: Implement prop and URL logic
+- Run `cd apps/web && npm test`
+
+---
+
+### Task 8: `TerminalSessionTabs` UI Component
+
+**Scope**: Build the tab bar for desktop and mobile.
+
+**Files to create**:
+- `apps/web/src/components/terminal-session-tabs.tsx`
+- `apps/web/src/components/terminal-session-tabs.test.tsx`
+
+**Acceptance Criteria**:
+- Props interface: `sessions`, `activeSessionId`, `onSelect`, `onClose`, `onCreate`, `onRename`, `isMobile?`
+- Desktop: horizontal tab strip above terminal, overflow scroll with fade indicator
+- Mobile: compact tabs integrated into auto-hide chrome, horizontal swipe scroll
+- Each tab shows: name, status dot (connecting/connected/disconnected/error), close button (×) on hover/active
+- Double-click to rename: inline `<input>`, `Enter` to confirm, `Escape` to cancel, blur confirms
+- New session button (+) at right end; disabled when 5 sessions exist
+- Close confirmation: lightweight inline confirm tooltip (not modal)
+- Accessible: `role="tablist"`, `role="tab"`, keyboard navigation
+
+**Testing (TDD)**:
+- RED: Write `terminal-session-tabs.test.tsx`:
+  - `test_renders_all_tabs`
+  - `test_click_tab_calls_onSelect`
+  - `test_close_button_calls_onClose`
+  - `test_double_click_enables_rename`
+  - `test_plus_disabled_at_max_sessions`
+  - `test_status_dot_reflects_connection_state`
+- GREEN: Implement component
+- Run `cd apps/web && npm test`
+
+---
+
+### Task 9: `TerminalPage` Multi-Session Orchestration, Fullscreen, and Shortcuts
+
+**Scope**: Rewrite `TerminalPage` to manage multiple mounted terminals, fullscreen mode, and keyboard shortcuts.
+
+**Files to modify**:
+- `apps/web/src/pages/terminal.tsx`
+
+**Acceptance Criteria**:
+- Uses `useTerminalSessions` hook
+- Renders `<TerminalSessionTabs />` above terminal area
+- Renders one `<TerminalComponent />` per session; inactive sessions hidden via `display: none` (preserves scrollback and WS)
+- On tab switch, active terminal calls `fitAddon.fit()` via ref + `useEffect` on visibility
+- Fullscreen toggle:
+  - `Ctrl+Shift+F` toggles `.fullscreen` class
+  - Desktop: hides page header; tab strip becomes minimal overlay (auto-hides after 3s, reappears on mouse move)
+  - Mobile: hides header, tab strip, special keys; floating handle reveals chrome
+  - Exit via `Esc` or UI button
+- Keyboard shortcuts (registered in `useEffect` on `keydown`):
+  - `Alt+Shift+N` — new session
+  - `Alt+Shift+W` — close current session
+  - `Alt+Shift+←` / `Alt+Shift+→` — prev/next session
+  - `Alt+Shift+R` — reset current session
+  - All use `preventDefault()` only for the exact combo; no browser overrides
+- Closing last session auto-creates a new default session
+
+**Testing (TDD)**:
+- RED: Add `terminal-page.test.tsx`:
+  - `test_creates_default_session_on_empty_load`
+  - `test_switching_tabs_hides_inactive_terminals`
+  - `test_fullscreen_toggle_adds_class`
+  - `test_keyboard_shortcut_creates_session`
+  - `test_close_last_session_auto_creates_default`
+- GREEN: Implement page orchestration
+- Run `cd apps/web && npm test`
+
+---
+
+### Task 10: Mobile Terminal Integration
+
+**Scope**: Integrate session tabs into mobile terminal wrapper and update header.
+
+**Files to modify**:
+- `apps/web/src/components/mobile-terminal-wrapper.tsx`
+- `apps/web/src/components/mobile-terminal-header.tsx`
+
+**Acceptance Criteria**:
+- `MobileTerminalWrapper` accepts session-related props from `TerminalPage` and passes them to `TerminalSessionTabs`
+- `MobileTerminalHeader` displays `activeSession.name` instead of generic `"Terminal"`
+- Tab strip shares `useAutoHide` behavior with header (tapping terminal toggles visibility)
+- Special keys strip remains functional; no z-index conflicts with tabs
+- Fullscreen on mobile correctly hides/shows all chrome layers
+
+**Testing (TDD)**:
+- RED: Add/update mobile wrapper tests:
+  - `test_renders_session_tabs`
+  - `test_header_shows_session_name`
+  - `test_auto_hide_applies_to_tabs`
+- GREEN: Implement mobile integration
+- Run `cd apps/web && npm test`
+
+---
+
+### Task 11: Backend Integration Tests
+
+**Scope**: Complete backend test coverage for multi-session WebSocket and REST behavior.
+
+**Files to create / modify**:
+- `apps/api/tests/services/test_terminal_manager_multi.py` (finalize)
+- `apps/api/tests/api/test_terminal_ws_multi.py` (finalize)
+
+**Acceptance Criteria**:
+- All tests from Tasks 2, 4, 5 pass
+- Additional integration tests:
+  - `test_list_sessions_after_api_restart_shows_db_metadata` (simulates restart by clearing in-memory dict)
+  - `test_two_websockets_on_same_session_receive_same_output`
+  - `test_idle_cleanup_per_session_not_global`
+- `make test` passes (unit + integration)
+
+**Testing (TDD)**:
+- These are the GREEN/TRIANGULATE phases for earlier backend tasks; ensure coverage is comprehensive
+
+---
+
+### Task 12: Frontend Component Tests
+
+**Scope**: Finalize frontend test coverage for tabs, page, and hook.
+
+**Files to create / modify**:
+- `apps/web/src/components/terminal-session-tabs.test.tsx` (finalize)
+- `apps/web/src/hooks/use-terminal-sessions.test.ts` (new, if not created earlier)
+- `apps/web/src/pages/terminal.test.tsx` (new)
+
+**Acceptance Criteria**:
+- Tab component tests cover rendering, selection, close, rename, and max-session disable
+- Hook tests cover load, create, close, error handling
+- Page tests cover session lifecycle, fullscreen, and keyboard shortcuts
+- `cd apps/web && npm test` passes
+
+**Testing (TDD)**:
+- Finalize RED→GREEN→TRIANGULATE for all frontend tasks
+
+---
+
+## Risks and Mitigations
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| Resource exhaustion (5× docker exec per instance) | Medium | High | Max 5 enforced in `create_session`. Idle timeout (30 min) applies per session. |
+| Mobile UX degraded by tab bar + special keys strip | Medium | Medium | Auto-hide shared between tabs and header. Compact tab design. Overflow scroll. |
+| Concurrent WS policy closes wrong session's sockets | Medium | High | Explicit unit test: `attach_websocket` must only affect same `(instance_id, session_id)`. |
+| DB writes on hot path (activity tracking) | Low | Medium | `last_activity_at` updates are fire-and-forget async tasks; do not block I/O loop. |
+| Frontend performance with 5 mounted xterm.js instances | Low | Medium | Max 5 sessions. Inactive terminals use `display: none` (not unmounted). xterm.js GPU acceleration handles this. |
+| Default session alias ambiguity | Low | Low | Document that `/terminal` maps to `"default"`. Future deprecation can migrate to explicit IDs. |
+| Browser shortcut conflicts | Low | Medium | Use `Alt+Shift+*` instead of `Ctrl+Shift+W/N`. Only `preventDefault()` on exact matching combos. |
+
+---
+
+## Rollback Plan
+
+- **PR 1 rollback**: Alembic downgrade removes `terminal_sessions` table. Old `TerminalManager` code is fully replaced, so reverting PR 1 requires reverting all subsequent PRs.
+- **PR 2 rollback**: Revert API changes. Legacy `/terminal` WS route and `POST .../terminal/reset` continue to work; new `/terminal/{session_id}` returns 404 but no clients call it until PR 3 is deployed.
+- **PR 3 rollback**: Revert frontend. Users see old single-session UI. Backend `/terminal` alias continues to serve them.
+
+Because PRs are stacked, rolling back PR 2 or PR 1 requires rolling back all dependent PRs above it.

openspec/designs/config-profile-multi-repo-mounts.md

@@ -0,0 +1,172 @@
+# Design: Config Profile Multi-Repo Mounts
+
+## Architecture
+
+### Data Model
+
+No database changes. The `git_mounts` JSONB column already stores arbitrary JSON.
+
+#### Normalized git mount schema (in memory)
+
+After validation/normalization, every git mount entry is converted to the unified form:
+
+```python
+{
+    "remote_url": str,
+    "branch": str | None,
+    "mappings": [
+        {"source_path": str, "target_path": str},
+        ...
+    ]
+}
+```
+
+The normalization step converts legacy `source_path` + `target_path` into a single-entry `mappings` array.
+
+### Backend Changes
+
+#### 1. `_resolve_single_git_mount` refactor
+
+Split into two functions:
+
+**`_clone_git_repo(remote_url, branch, clone_parent) -> repo_path`**
+- Clones or pulls the repo
+- Returns the path to `repo-clone`
+- Same as before, but extracts the clone logic
+
+**`_resolve_git_mount_mappings(repo_path, mappings, working_directory) -> list[dict]`**
+- Takes the already-cloned repo path
+- For each mapping:
+  1. Build source path: `os.path.join(repo_path, mapping["source_path"])`
+  2. Expand globs via `_expand_glob_source`
+  3. Resolve target path (absolute or relative to working_directory)
+  4. Build volume mount entries
+- Returns list of volume mount dicts
+
+**`_resolve_single_git_mount` new flow:**
+1. Validate entry (remote_url, mappings or source_path+target_path)
+2. Normalize legacy format to `mappings` array
+3. Compute clone directory (same as before: `git-mounts/{repo_name}-{hash}/`)
+4. Clone/pull repo
+5. Resolve all mappings from the cloned repo
+6. Return flat list of volume mounts
+
+#### 2. `_merge_git_mounts` update
+
+The merge key changes from `(remote_url, target_path)` to `(remote_url, branch)`.
+
+When two entries have the same `remote_url` and `branch`, their `mappings` arrays are concatenated. When different, they are kept as separate entries.
+
+```python
+def _merge_git_mounts(base, overlay, source_name):
+    result = list(base)
+    seen = {}
+    for i, m in enumerate(result):
+        key = (m["remote_url"], m.get("branch"))
+        seen[key] = i
+
+    for mount in overlay:
+        key = (mount["remote_url"], mount.get("branch"))
+        if key in seen:
+            # Same repo+branch: concatenate mappings
+            result[seen[key]]["mappings"].extend(mount.get("mappings", []))
+        else:
+            seen[key] = len(result)
+            result.append(dict(mount))
+    return result
+```
+
+#### 3. Validation on save
+
+In the Config Profile API (create/update), validate `git_mounts`:
+- Each entry must have `remote_url`
+- Each entry must have either `mappings` OR (`source_path` AND `target_path`)
+- Each mapping must have `source_path` and `target_path`
+- `mappings` must be a non-empty array
+
+### Frontend Changes
+
+#### GitMountEditor component
+
+New or updated component for editing a single git mount entry:
+
+```
+Remote URL:    [____________________]
+Branch:        [main________________]
+
+Mappings:
+  Source Path        →  Target Path
+  [packages/api  ]      [/app/api    ]  [×]
+  [packages/web  ]      [/app/web    ]  [×]
+  [              ]      [            ]  [+ Add]
+```
+
+**State shape:**
+```typescript
+interface GitMountMapping {
+  source_path: string;
+  target_path: string;
+}
+
+interface GitMountEntry {
+  remote_url: string;
+  branch?: string;
+  mappings: GitMountMapping[];
+  // Legacy fields (read-only for old data)
+  source_path?: string;
+  target_path?: string;
+}
+```
+
+**Migration on load:** If an entry has `source_path` and `target_path` but no `mappings`, auto-convert:
+```typescript
+if (!entry.mappings && entry.source_path && entry.target_path) {
+  entry.mappings = [{ source_path: entry.source_path, target_path: entry.target_path }];
+}
+```
+
+### File Changes
+
+| File | Change |
+|------|--------|
+| `apps/api/src/api/tool_instances.py` | Refactor `_resolve_single_git_mount` to support mappings |
+| `apps/api/src/services/config_profile_resolver.py` | Update `_merge_git_mounts` merge key |
+| `apps/api/src/api/config_profiles.py` | Add validation for git_mounts schema |
+| `apps/web/src/components/config-profile-editor.tsx` | Add mappings UI for git mounts |
+| `apps/web/src/api/config_profiles.ts` | Update types for GitMountEntry |
+| `apps/api/tests/unit/test_git_mounts.py` | New unit tests for multi-mapping resolution |
+| `apps/api/tests/unit/test_config_profile_resolver.py` | Update merge tests |
+
+### Testing Strategy
+
+#### Backend unit tests
+
+1. `_resolve_single_git_mount` with 3 mappings → single clone, 3 mounts
+2. `_resolve_single_git_mount` legacy format → single clone, 1 mount
+3. `_merge_git_mounts` same repo+branch → mappings concatenated
+4. `_merge_git_mounts` different repos → separate entries
+5. Validation: entry with neither mappings nor source_path → error
+6. Validation: mapping missing target_path → error
+
+#### Integration tests
+
+1. Create profile with 2 mappings from same repo → start instance → verify single clone directory
+2. Create profile with legacy format → start instance → verify backward compatibility
+
+#### Frontend tests
+
+1. GitMountEditor renders mappings list
+2. Adding a mapping updates state correctly
+3. Legacy entry auto-converts on load
+4. Save sends correct JSON shape
+
+### Migration Plan
+
+No database migration. Existing `git_mounts` JSON continues to work because:
+- The code normalizes legacy `source_path` + `target_path` to `mappings` on read
+- The frontend auto-converts on load
+- New saves use the `mappings` format
+
+### Rollback Plan
+
+Since there is no schema change, rollback is just reverting the code. Existing profiles with the new `mappings` format will still parse correctly even with old code if we keep the normalization shim.

openspec/designs/home-path-expansion.md

@@ -0,0 +1,102 @@
+# Design: ~ / $HOME Expansion in Mount Paths
+
+## Architecture
+
+### New Helpers
+
+#### `expand_container_path(path: str, home_dir: str) -> str`
+Located in `config_profile_resolver.py` (or new shared module).
+
+```python
+def expand_container_path(path: str, home_dir: str) -> str:
+    if path.startswith("~/"):
+        return os.path.join(home_dir, path[2:])
+    if path == "~":
+        return home_dir
+    path = path.replace("$HOME/", home_dir + "/")
+    path = path.replace("$HOME", home_dir)
+    return path
+```
+
+#### `get_manifest_home_dir(manifest: dict) -> str`
+Located in `manifest_compiler.py`.
+
+```python
+def get_manifest_home_dir(manifest: dict) -> str:
+    user = manifest.get("user")
+    if user and user.get("name"):
+        return f"/home/{user['name']}"
+    return "/root"
+```
+
+#### `get_tool_home_dir(tool_type: ToolType, manifest: dict | None) -> str`
+Located in `tool_instances.py` or `manifest_compiler.py`.
+
+```python
+def get_tool_home_dir(tool_type: ToolType, manifest: dict | None = None) -> str:
+    if tool_type.definition_type == "manifest" and manifest:
+        return get_manifest_home_dir(manifest)
+    return "/root"
+```
+
+### Pipeline Changes
+
+#### `create_instance` flow
+
+1. Determine `home_dir` from tool type + manifest (if manifest-based)
+2. Pass `home_dir` to `_modify_compose_file()` — expand mount targets in compose
+
+#### `start_instance` flow
+
+1. Determine `home_dir` from tool type + resolved manifest
+2. Pass `home_dir` to `apply_resolved_profile()` — expand profile mount targets
+3. Pass `home_dir` to `_resolve_git_mounts()` — expand git mount mapping targets
+
+#### `apply_resolved_profile()`
+
+```python
+def apply_resolved_profile(
+    instance_dir: str,
+    resolved: ResolvedProfile,
+    home_dir: str = "/root",
+) -> tuple[...]:
+    ...
+    for mount in resolved.mounts.values():
+        target = expand_container_path(mount.target, home_dir)
+        ...
+```
+
+#### `_resolve_git_mount_mappings()`
+
+```python
+def _resolve_git_mount_mappings(
+    repo_path: str,
+    mappings: list[dict],
+    working_directory: str | None,
+    home_dir: str = "/root",
+) -> list[dict]:
+    ...
+    final_target = expand_container_path(target_path, home_dir)
+    ...
+```
+
+### Dockerfile Change
+
+In `compile_dockerfile()`, after user creation, set `HOME`:
+
+```python
+if user:
+    home = f"/home/{user['name']}"
+    lines.append(f"ENV HOME={home}")
+    lines.append(f"ENV USER={user['name']}")
+```
+
+### File Changes
+
+| File | Change |
+|------|--------|
+| `apps/api/src/services/config_profile_resolver.py` | Add `expand_container_path()`, apply in `apply_resolved_profile()` |
+| `apps/api/src/services/manifest_compiler.py` | Add `get_manifest_home_dir()`, set `HOME`/`USER` env in Dockerfile |
+| `apps/api/src/api/tool_instances.py` | Determine `home_dir`, pass through all mount resolution functions |
+| `apps/api/tests/unit/test_home_path_expansion.py` | New unit tests |
+| `apps/api/tests/unit/test_manifest_compiler.py` | Add tests for `get_manifest_home_dir` and Dockerfile `HOME` env |

openspec/explorations/config-profile-multi-repo-mounts.md

@@ -0,0 +1,120 @@
+# Exploration: Config Profile Multi-Repo Mounts
+
+## Problem
+
+Config Profiles support `git_mounts` — cloning repositories and mounting them into containers. However, each `git_mount` entry clones **one** source path from **one** repo. If a user wants to mount multiple directories from the same repository (e.g., a monorepo), they must add multiple `git_mount` entries, which results in **cloning the same repository multiple times**.
+
+### Current git_mount schema (one mapping per entry)
+
+```json
+{
+  "remote_url": "https://github.com/user/monorepo.git",
+  "source_path": "packages/backend",
+  "target_path": "/app/backend",
+  "branch": "main"
+}
+```
+
+To mount 3 directories from the same monorepo, the profile needs 3 entries, each triggering a separate clone of the full repository.
+
+## Pain Points
+
+1. **Redundant clones**: Cloning the same repo N times wastes time and disk space.
+2. **Slow instance startup**: Each clone adds 5-30 seconds depending on repo size.
+3. **Inconsistent branch state**: Each entry independently checks out the branch — they could drift if the branch moves between clones.
+4. **Poor monorepo support**: Monorepos are common; users expect to mount multiple packages.
+
+## Scenarios
+
+### Scenario A: Monorepo with multiple packages
+
+User has a monorepo `corp/monorepo` with:
+- `packages/api` → needs to be at `/app/api`
+- `packages/web` → needs to be at `/app/web`
+- `packages/shared` → needs to be at `/app/shared`
+
+They want to mount all three into a single tool instance.
+
+### Scenario B: Docs + Code sidecar
+
+User wants to mount both:
+- `src/` → `/workspace/src`
+- `docs/` → `/workspace/docs`
+
+from the same repo.
+
+### Scenario C: Backward compatibility
+
+Existing profiles with single `source_path`/`target_path` should continue working without migration.
+
+## Design Directions
+
+### Direction A: `mappings` array on git_mount entry
+
+Add a `mappings` array to each git_mount entry. The repo is cloned once, and each mapping creates a separate bind mount.
+
+```json
+{
+  "remote_url": "https://github.com/user/monorepo.git",
+  "branch": "main",
+  "mappings": [
+    {"source_path": "packages/api", "target_path": "/app/api"},
+    {"source_path": "packages/web", "target_path": "/app/web"}
+  ]
+}
+```
+
+**Pros**:
+- Clean, explicit grouping
+- Single clone per `remote_url + branch` combo
+- Easy to understand
+- Backward-compatible: legacy `source_path` + `target_path` can be treated as a single-entry `mappings` array
+
+**Cons**:
+- Slightly more verbose JSON
+- Frontend form needs a nested list UI
+
+### Direction B: Auto-dedup by remote_url + branch
+
+Keep the flat list format, but internally group entries by `remote_url + branch` and clone once.
+
+```json
+[
+  {"remote_url": "...", "source_path": "a", "target_path": "/a", "branch": "main"},
+  {"remote_url": "...", "source_path": "b", "target_path": "/b", "branch": "main"}
+]
+```
+
+**Pros**:
+- No schema change
+- Transparent to users
+
+**Cons**:
+- Magic behavior (not obvious why clones are shared)
+- Harder to reason about branch conflicts (what if same repo, different branches?)
+- Frontend doesn't show the grouping
+
+### Direction C: Repo references + mount definitions split
+
+Split into two concepts:
+1. `git_repos` — list of repos to clone (with branch)
+2. `git_mounts` — reference a repo by name and specify source/target
+
+**Pros**:
+- Very explicit
+- Supports advanced scenarios (SSH keys per repo)
+
+**Cons**:
+- Breaking schema change
+- Overkill for the current use case
+- Heavy migration burden
+
+## Recommendation
+
+**Direction A (mappings array)** with backward-compatibility shim:
+- Add optional `mappings` field to git_mount entries
+- If `mappings` is absent, treat `source_path` + `target_path` as a single mapping
+- Clone once per `remote_url + branch`, apply all mappings from the same entry
+- No migration needed for existing data
+
+This balances clarity, functionality, and backward compatibility.

openspec/explorations/home-path-expansion.md

@@ -0,0 +1,76 @@
+# Exploration: ~ / $HOME Expansion in Mount Paths
+
+## User Request
+Allow `~` and `$HOME` in mount paths for both regular mounts and git mounts.
+
+## Where This Applies
+
+### Container target paths (where it makes sense)
+- **Regular mounts** (`mount.target`): The absolute path inside the container where files are bind-mounted
+- **Git mount mappings** (`mapping.target_path`): The absolute path inside the container where repo subdirectories are mounted
+
+### Where it does NOT apply
+- **Regular mount file paths** (`mount.files` keys): These are relative to the mount target
+- **Git mount source paths** (`mapping.source_path`): These are relative to the cloned repo
+- **Host-side source paths**: The API runs in a container; `~` on the host would mean the Docker host's home, which the API container cannot access
+
+## Complexity Assessment
+
+### The Core Problem
+`~` means "user's home directory". But whose home?
+
+| Context | Home Directory | Knowable at Mount Time? |
+|---------|---------------|------------------------|
+| API container | `/root` or `/app` | Yes |
+| Target container (manifest, user=root) | `/root` | Yes (from manifest) |
+| Target container (manifest, user=user) | `/home/user` | Yes (from manifest) |
+| Target container (legacy tool type) | Unknown | No (assume `/root`) |
+| Docker host | `/home/alex` or similar | No (API is containerized) |
+
+### Docker Compose Reality Check
+Docker Compose **does not expand** `~` or `$HOME` in volume targets. These are passed literally to the Docker daemon. So `~/workspace` becomes a directory literally named `~` in the container root.
+
+This means **we must resolve the path ourselves** before writing the compose file.
+
+## Design Options
+
+### Option A: Simple `/root` default (minimal change)
+- Replace `~` and `$HOME` with `/root` in all container target paths
+- Apply during compose modification and git mount resolution
+- **Effort**: ~30 min, ~20 lines
+- **Pros**: Dead simple, works for root-running containers (most legacy setups)
+- **Cons**: Wrong for pi-agent (runs as `user`, home `/home/user`)
+
+### Option B: Manifest-aware home directory (recommended)
+- For manifest-based tools: read `user.name` from manifest, compute home as `/home/{name}` or `/root`
+- For legacy tools: default to `/root`
+- Pass `home_dir` through the mount resolution pipeline
+- Apply expansion in `apply_resolved_profile()` and `_resolve_git_mount_mappings()`
+- **Effort**: ~2 hours, touches 3-4 files
+- **Pros**: Correct for all container types
+- **Cons**: Slightly more plumbing
+
+### Option C: Configurable home per profile
+- Add `home_directory` field to ConfigProfile
+- User can override the container home directory
+- **Effort**: ~3 hours, schema change
+- **Cons**: Overkill, clutters UI
+
+## Recommendation
+
+**Option B** — manifest-aware expansion. The pi-agent manifest already declares `user.name`, so we can compute the correct home directory. For backward compatibility, legacy tool types default to `/root`.
+
+## Files to Touch
+
+1. `apps/api/src/services/config_profile_resolver.py` — add `expand_container_path()` helper
+2. `apps/api/src/api/tool_instances.py` — pass `home_dir` to `apply_resolved_profile()` and git mount functions; determine home from manifest/tool type
+3. `apps/api/src/services/manifest_compiler.py` — expose helper to extract user from manifest
+4. Tests for expansion logic
+
+## Risks
+
+| Risk | Mitigation |
+|------|------------|
+| Wrong home for custom containers | Document that manifest should declare `user.name` |
+| `$HOME` env var not set in container | We resolve it at compose generation time, so no runtime dependency |
+| Breaking existing profiles with literal `~` in path | Very unlikely; we can add an escape hatch if needed |

openspec/proposals/config-profile-multi-repo-mounts.md

@@ -0,0 +1,50 @@
+# Proposal: Config Profile Multi-Repo Mounts
+
+## Context
+
+Config Profiles allow users to mount external Git repositories into tool instances via `git_mounts`. Currently, each `git_mount` entry supports only **one** source_path → target_path mapping. If a user wants to mount multiple directories from the same repository (e.g., a monorepo), they must add multiple entries, each cloning the repository independently.
+
+## Goal
+
+Enable a single `git_mount` entry to declare **multiple** source/target mappings from the same repository, while cloning the repository only once per entry.
+
+## Direction
+
+**Direction A: `mappings` array with backward compatibility**
+
+Add an optional `mappings` array to each `git_mount` entry. The repository is cloned once, and each mapping creates a separate bind mount from a subdirectory of the cloned repo.
+
+If `mappings` is absent, the existing `source_path` + `target_path` fields are treated as a single mapping (backward-compatible).
+
+## Acceptance Criteria
+
+1. A `git_mount` entry can specify `mappings: [{"source_path": "...", "target_path": "..."}, ...]`
+2. The repository is cloned **exactly once** per `git_mount` entry
+3. Each mapping creates a separate Docker bind mount from the cloned repo subdirectory
+4. Existing profiles with `source_path`/`target_path` continue working without migration
+5. The Config Profile editor UI supports adding/removing mappings per git mount
+6. Glob patterns are supported in `source_path` within mappings
+7. Relative `target_path` values are resolved against `working_directory` as before
+
+## Out of Scope
+
+- Cross-entry repo deduplication (two separate git_mount entries with the same `remote_url` still clone twice)
+- SSH key per-repo configuration (can be added later)
+- Sparse checkout / partial clone optimization
+- Mounting from non-Git sources
+
+## Risks
+
+| Risk | Mitigation |
+|------|------------|
+| Schema migration complexity | No migration needed — backward-compatible |
+| Frontend UI complexity | Nested form with add/remove mapping buttons |
+| Clone directory sharing race condition | Each entry gets its own clone directory (url_hash based) |
+| Large monorepo clone time | Out of scope — full clone is existing behavior |
+
+## Related Artifacts
+
+- Exploration: `openspec/explorations/config-profile-multi-repo-mounts.md`
+- Spec: `openspec/specs/config-profile-multi-repo-mounts.md`
+- Design: `openspec/designs/config-profile-multi-repo-mounts.md`
+- Tasks: `openspec/tasks/config-profile-multi-repo-mounts.md`

openspec/proposals/home-path-expansion.md

@@ -0,0 +1,49 @@
+# Proposal: ~ / $HOME Expansion in Mount Paths
+
+## Context
+
+Users want to write mount target paths like `~/workspace` or `$HOME/workspace` instead of absolute paths like `/home/user/workspace` or `/root/workspace`. Docker Compose does not expand these — they must be resolved before writing the compose file.
+
+## Goal
+
+Resolve `~` and `$HOME` in container target paths to the correct home directory for the target container.
+
+## Direction
+
+**Manifest-aware home directory (Option B)**
+- Extract `user.name` from the tool manifest to compute `/home/{name}`
+- For root-based manifests (no user block), use `/root`
+- For legacy tool types (non-manifest), default to `/root`
+- Apply expansion at compose generation time for both regular mounts and git mount targets
+- Also set `HOME` env var in the Dockerfile for runtime compatibility
+
+## Acceptance Criteria
+
+1. `~` in a mount target path is expanded to the container's home directory
+2. `$HOME` in a mount target path is expanded to the container's home directory
+3. For manifest-based tools with `user.name`, home is `/home/{user.name}`
+4. For manifest-based tools without user block, home is `/root`
+5. For legacy tool types, home is `/root`
+6. Git mount `mapping.target_path` also supports `~` and `$HOME`
+7. `HOME` env var is set in generated Dockerfile
+8. No frontend changes needed (users type `~`, backend resolves it)
+
+## Out of Scope
+
+- `~` expansion in host-side source paths
+- `~` expansion in mount file relative paths
+- `~user` syntax (e.g., `~alice`)
+
+## Risks
+
+| Risk | Mitigation |
+|------|------------|
+| Wrong home for custom containers | Document that manifest should declare `user.name` |
+| `$HOME` env var not set in container | Set it in Dockerfile via `ENV HOME=...` |
+
+## Related Artifacts
+
+- Exploration: `openspec/explorations/home-path-expansion.md`
+- Spec: `openspec/specs/home-path-expansion.md`
+- Design: `openspec/designs/home-path-expansion.md`
+- Tasks: `openspec/tasks/home-path-expansion.md`

openspec/specs/config-profile-multi-repo-mounts.md

@@ -0,0 +1,119 @@
+# Spec: Config Profile Multi-Repo Mounts
+
+## Requirements
+
+### Functional
+
+1. **FR-1**: A `git_mount` entry MAY include a `mappings` array.
+2. **FR-2**: Each item in `mappings` MUST have `source_path` and `target_path`.
+3. **FR-3**: If `mappings` is absent, `source_path` and `target_path` at the entry level MUST be treated as a single mapping (backward compatibility).
+4. **FR-4**: The repository MUST be cloned exactly once per `git_mount` entry.
+5. **FR-5**: Each mapping MUST create a separate Docker bind mount.
+6. **FR-6**: Glob patterns in `source_path` MUST be expanded per mapping.
+7. **FR-7**: Relative `target_path` values MUST be resolved against `working_directory`.
+8. **FR-8**: The merge logic for included profiles MUST deduplicate by `(remote_url, branch)` within a single resolved profile's `git_mounts` list.
+
+### Non-Functional
+
+1. **NFR-1**: No database schema migration required.
+2. **NFR-2**: Existing API responses must remain backward-compatible.
+3. **NFR-3**: Frontend type-check must pass without errors.
+
+## API Contracts
+
+### ConfigProfile model (git_mounts field)
+
+```json
+{
+  "git_mounts": [
+    {
+      "remote_url": "https://github.com/user/monorepo.git",
+      "branch": "main",
+      "mappings": [
+        {"source_path": "packages/api", "target_path": "/app/api"},
+        {"source_path": "packages/web", "target_path": "/app/web"}
+      ]
+    },
+    {
+      "remote_url": "https://github.com/user/docs.git",
+      "source_path": ".",
+      "target_path": "/docs",
+      "branch": "main"
+    }
+  ]
+}
+```
+
+### Validation rules
+
+1. `mappings` must be a non-empty array if present.
+2. Each mapping must have `source_path` (string) and `target_path` (string).
+3. Either `mappings` OR (`source_path` AND `target_path`) must be present.
+4. `remote_url` must be a valid HTTPS or SSH Git URL.
+
+## Database Schema
+
+No changes. `git_mounts` is stored as JSONB in `config_profiles.git_mounts`.
+
+## Scenarios
+
+### Scenario 1: Monorepo with multiple packages
+
+**Given** a Config Profile with:
+```json
+{"git_mounts": [{
+  "remote_url": "https://github.com/corp/monorepo.git",
+  "branch": "main",
+  "mappings": [
+    {"source_path": "packages/api", "target_path": "/app/api"},
+    {"source_path": "packages/web", "target_path": "/app/web"},
+    {"source_path": "packages/shared", "target_path": "/app/shared"}
+  ]
+}]}
+```
+
+**When** the profile is applied to an instance
+
+**Then**:
+1. `corp/monorepo` is cloned once to `git-mounts/monorepo-{hash}/repo-clone`
+2. Three bind mounts are created:
+   - `{clone}/packages/api` → `/app/api`
+   - `{clone}/packages/web` → `/app/web`
+   - `{clone}/packages/shared` → `/app/shared`
+
+### Scenario 2: Legacy single mapping (backward compatibility)
+
+**Given** a Config Profile with:
+```json
+{"git_mounts": [{
+  "remote_url": "https://github.com/user/repo.git",
+  "source_path": "src",
+  "target_path": "/workspace/src",
+  "branch": "main"
+}]}
+```
+
+**When** the profile is applied
+
+**Then** the behavior is identical to before (single clone, single mount).
+
+### Scenario 3: Glob expansion within mapping
+
+**Given** a mapping with:
+```json
+{"source_path": "packages/*", "target_path": "/app/packages"}
+```
+
+**When** the repo is cloned and the glob is expanded
+
+**Then** each matched directory is mounted as a separate bind mount with the relative path appended to the target:
+- `{clone}/packages/api` → `/app/packages/api`
+- `{clone}/packages/web` → `/app/packages/web`
+
+## Test Strategy
+
+1. Unit test `_resolve_single_git_mount` with `mappings` array
+2. Unit test `_merge_git_mounts` with mappings deduplication
+3. Integration test: profile with 3 mappings from same repo → verify single clone
+4. Integration test: legacy profile without `mappings` → verify backward compatibility
+5. Frontend unit test: GitMountEditor renders mappings form correctly

openspec/specs/home-path-expansion.md

@@ -0,0 +1,71 @@
+# Spec: ~ / $HOME Expansion in Mount Paths
+
+## Requirements
+
+### Functional
+
+1. **FR-1**: `~` in mount target paths MUST be expanded to the container's home directory.
+2. **FR-2**: `$HOME` in mount target paths MUST be expanded to the container's home directory.
+3. **FR-3**: For manifest-based tools with `user.name`, home MUST be `/home/{user.name}`.
+4. **FR-4**: For manifest-based tools without user block, home MUST be `/root`.
+5. **FR-5**: For legacy tool types, home MUST be `/root`.
+6. **FR-6**: Git mount `mapping.target_path` MUST support `~` and `$HOME`.
+7. **FR-7**: The generated Dockerfile MUST set `HOME` env var.
+
+### Non-Functional
+
+1. **NFR-1**: No database schema changes.
+2. **NFR-2**: No frontend changes.
+3. **NFR-3**: Existing profiles without `~` MUST continue working.
+
+## API Contracts
+
+No API changes. Resolution happens server-side during compose generation.
+
+## Scenarios
+
+### Scenario 1: pi-agent with ~ mount
+
+**Given** a Config Profile with:
+```json
+{"mounts": [{"target": "~/workspace", "mode": "rw", "files": {}}]}
+```
+
+**And** a pi-agent manifest with `user.name = "user"`
+
+**When** the profile is applied
+
+**Then** the compose file contains `/home/user/workspace` as the mount target.
+
+### Scenario 2: Legacy tool with $HOME mount
+
+**Given** a Config Profile with:
+```json
+{"mounts": [{"target": "$HOME/config", "mode": "ro", "files": {}}]}
+```
+
+**And** a legacy tool type (no manifest)
+
+**When** the profile is applied
+
+**Then** the compose file contains `/root/config` as the mount target.
+
+### Scenario 3: Git mount with ~ target
+
+**Given** a Config Profile with:
+```json
+{"git_mounts": [{"remote_url": "...", "mappings": [{"source_path": ".", "target_path": "~/repo"}]}]}
+```
+
+**And** a manifest with `user.name = "user"`
+
+**When** the profile is applied
+
+**Then** the compose file contains `/home/user/repo` as the mount target.
+
+## Test Strategy
+
+1. Unit test `expand_container_path` with `~`, `$HOME`, absolute paths, relative paths
+2. Unit test `get_manifest_home_dir` with user block, without user block
+3. Integration test: profile with `~` mount applied to pi-agent instance
+4. Integration test: profile with `$HOME` mount applied to legacy instance

openspec/tasks/config-profile-multi-repo-mounts.md

@@ -0,0 +1,132 @@
+# Tasks: Config Profile Multi-Repo Mounts
+
+## T1: Backend — Refactor git mount resolution for mappings
+
+### T1.1: Normalize legacy git mount format
+**File**: `apps/api/src/api/tool_instances.py`
+- Add `_normalize_git_mount(entry: dict) -> dict` helper
+- Converts `{"source_path": "...", "target_path": "..."}` to `{"mappings": [{...}]}`
+- Call normalization at the start of `_resolve_single_git_mount`
+
+### T1.2: Extract clone logic
+**File**: `apps/api/src/api/tool_instances.py`
+- Create `_clone_git_repo(remote_url, branch, clone_parent) -> str` function
+- Move clone/pull logic from `_resolve_single_git_mount` into it
+- Returns `repo_path` (path to `repo-clone`)
+
+### T1.3: Resolve mappings from cloned repo
+**File**: `apps/api/src/api/tool_instances.py`
+- Create `_resolve_git_mount_mappings(repo_path, mappings, working_directory) -> list[dict]`
+- Iterates over mappings, expands globs, resolves targets
+- Returns flat list of volume mount dicts
+
+### T1.4: Wire it together
+**File**: `apps/api/src/api/tool_instances.py`
+- Update `_resolve_single_git_mount` to:
+  1. Normalize entry
+  2. Clone repo once
+  3. Resolve all mappings
+  4. Return flat volume mounts
+
+### T1.5: Update merge logic
+**File**: `apps/api/src/services/config_profile_resolver.py`
+- Change `_merge_git_mounts` merge key from `(remote_url, target_path)` to `(remote_url, branch)`
+- When same repo+branch: concatenate `mappings` arrays
+- When different: append as separate entry
+
+### T1.6: Add validation
+**File**: `apps/api/src/api/config_profiles.py`
+- Validate `git_mounts` on create/update:
+  - `remote_url` required
+  - Either `mappings` (non-empty array) OR (`source_path` + `target_path`)
+  - Each mapping has `source_path` and `target_path`
+
+### T1.7: Unit tests
+**File**: `apps/api/tests/unit/test_git_mounts.py` (new)
+- Test normalization: legacy → mappings
+- Test single clone with 3 mappings → 3 volume mounts
+- Test glob expansion within mapping
+- Test relative target resolution
+
+**File**: `apps/api/tests/unit/test_config_profile_resolver.py`
+- Update merge tests for new dedup key
+
+---
+
+## T2: Frontend — Git mount mappings editor
+
+### T2.1: Update types
+**File**: `apps/web/src/api/config_profiles.ts`
+- Add `GitMountMapping` interface
+- Update `GitMountEntry` to have `mappings: GitMountMapping[]`
+- Keep optional `source_path`/`target_path` for backward compat
+
+### T2.2: Auto-convert legacy entries on load
+**File**: `apps/web/src/components/config-profile-editor.tsx` or new `GitMountEditor.tsx`
+- On loading a profile, normalize any git_mount entries that lack `mappings`
+
+### T2.3: Build mappings UI
+**File**: `apps/web/src/components/GitMountEditor.tsx` (new)
+- Render table/list of mappings per git mount entry
+- "Add mapping" button appends empty row
+- "Remove" button deletes a mapping row
+- Source path and target path inputs
+
+### T2.4: Integrate into ConfigProfileEditor
+**File**: `apps/web/src/components/config-profile-editor.tsx`
+- Replace existing git_mounts flat form with GitMountEditor component
+- Ensure save sends correct JSON shape
+
+### T2.5: Frontend tests
+**File**: `apps/web/src/components/GitMountEditor.test.tsx` (new)
+- Render with 2 mappings
+- Add mapping increases count
+- Remove mapping decreases count
+- Legacy entry auto-converts
+
+---
+
+## T3: Integration & Verification
+
+### T3.1: Integration test
+**File**: `apps/api/tests/integration/test_config_profiles_git_mounts.py` (new)
+- Create profile with 2 mappings from same repo
+- Start instance
+- Verify single clone directory exists
+- Verify 2 bind mounts in compose file
+
+### T3.2: Manual verification
+- Create a Config Profile with a monorepo git mount + 3 mappings
+- Create and start a pi-agent instance with the profile
+- Verify all 3 directories are mounted correctly
+- Verify legacy profile (single mapping) still works
+
+### T3.3: Typecheck & tests
+```bash
+cd apps/web && npm run typecheck
+cd apps/api && pytest tests/unit/test_git_mounts.py tests/unit/test_config_profile_resolver.py
+```
+
+---
+
+## Estimation
+
+| Task | Effort | Files |
+|------|--------|-------|
+| T1.1-T1.4 | 2h | 1 |
+| T1.5 | 1h | 1 |
+| T1.6 | 1h | 1 |
+| T1.7 | 2h | 2 |
+| T2.1-T2.4 | 3h | 3 |
+| T2.5 | 1h | 1 |
+| T3.1-T3.3 | 2h | 2 |
+| **Total** | **12h** | **11** |
+
+## PR Strategy
+
+**Single PR** (~400 lines estimated, within review budget):
+- Backend changes (T1)
+- Frontend changes (T2)
+- Tests (T1.7, T2.5, T3.1)
+
+All changes are tightly coupled (backend schema + frontend UI + tests) so a single PR is appropriate.

openspec/tasks/home-path-expansion.md

@@ -0,0 +1,75 @@
+# Tasks: ~ / $HOME Expansion in Mount Paths
+
+## T1: Backend — Core helpers and pipeline
+
+### T1.1: Add `expand_container_path` helper
+**File**: `apps/api/src/services/config_profile_resolver.py`
+- Add `expand_container_path(path: str, home_dir: str) -> str`
+- Handle `~/`, `~`, `$HOME/`, `$HOME` patterns
+- Must not expand if path doesn't start with these patterns
+
+### T1.2: Add `get_manifest_home_dir` helper
+**File**: `apps/api/src/services/manifest_compiler.py`
+- Add `get_manifest_home_dir(manifest: dict) -> str`
+- Returns `/home/{user.name}` if user block exists, else `/root`
+
+### T1.3: Set `HOME` and `USER` env vars in Dockerfile
+**File**: `apps/api/src/services/manifest_compiler.py`
+- In `compile_dockerfile()`, after user creation block, add `ENV HOME=...` and `ENV USER=...`
+- Update existing manifest compiler tests
+
+### T1.4: Update `apply_resolved_profile` to expand paths
+**File**: `apps/api/src/services/config_profile_resolver.py`
+- Add `home_dir: str = "/root"` parameter
+- Expand mount targets before creating mount directories and volume entries
+
+### T1.5: Update git mount resolution to expand paths
+**File**: `apps/api/src/api/tool_instances.py`
+- Add `home_dir: str = "/root"` parameter to `_resolve_git_mount_mappings()`
+- Expand mapping target paths before resolving
+- Add `home_dir` parameter to `_resolve_git_mounts()` and `_resolve_single_git_mount()`
+
+### T1.6: Determine home_dir in instance lifecycle
+**File**: `apps/api/src/api/tool_instances.py`
+- In `create_instance`: determine `home_dir` from tool type + manifest (if manifest), pass to `_modify_compose_file`
+- In `start_instance`: determine `home_dir` from tool type + resolved manifest, pass to `apply_resolved_profile` and `_resolve_git_mounts`
+- In `_prepare_manifest_instance`: return `home_dir` alongside image_tag and compose_content
+
+### T1.7: Update `_modify_compose_file` to expand paths
+**File**: `apps/api/src/api/tool_instances.py`
+- Add `home_dir: str = "/root"` parameter
+- Expand `working_directory` and any mount targets in extra_volumes
+
+### T1.8: Unit tests
+**File**: `apps/api/tests/unit/test_home_path_expansion.py` (new)
+- Test `expand_container_path` with `~`, `~/foo`, `$HOME`, `$HOME/foo`, `/abs/path`, `rel/path`
+- Test `get_manifest_home_dir` with user, without user
+
+**File**: `apps/api/tests/unit/test_manifest_compiler.py`
+- Test Dockerfile contains `ENV HOME=...` for user-based manifests
+- Test Dockerfile contains `ENV HOME=/root` for root manifests
+
+---
+
+## T2: Verification
+
+### T2.1: Run all affected tests
+```bash
+cd apps/api && pytest tests/unit/test_home_path_expansion.py tests/unit/test_manifest_compiler.py tests/unit/test_config_profile_resolver.py tests/unit/test_git_mounts.py -xvs
+```
+
+### T2.2: Frontend typecheck
+```bash
+cd apps/web && npm run typecheck
+```
+
+---
+
+## Estimation
+
+| Task | Effort | Files |
+|------|--------|-------|
+| T1.1-T1.7 | 2h | 3 |
+| T1.8 | 1h | 2 |
+| T2.1-T2.2 | 0.5h | — |
+| **Total** | **3.5h** | **5** |

scripts/fix_ghost_migration.sh

@@ -0,0 +1,18 @@
+#!/bin/bash
+# Fix ghost migration on production server
+# Run this INSIDE the api container or on the server
+
+echo "=== Checking for ghost migration file ==="
+find /app/alembic/versions -name "*tool_definition*" 2>/dev/null
+
+echo ""
+echo "=== Current alembic_version in DB ==="
+psql "$DATABASE_URL" -c "SELECT * FROM alembic_version;"
+
+echo ""
+echo "=== Checking if tool_types has definition_manifests column ==="
+psql "$DATABASE_URL" -c "\d tool_types" | grep -i manifest
+
+echo ""
+echo "=== Our known migration heads ==="
+grep -r "revision.*=" /app/alembic/versions/*.py | grep "2026_05_28"

scripts/update_db_password.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+"""Securely update the PostgreSQL password for the headquarter database user.
+
+Usage:
+    python scripts/update_db_password.py
+
+The script will prompt for the new password (no echo) and update it via the
+running hq-postgres Docker container.
+
+After running, remember to update your .env file:
+    POSTGRES_PASSWORD=<your-new-password>
+"""
+
+import getpass
+import subprocess
+import sys
+
+
+def main() -> None:
+    # Prompt for new password securely (no echo to terminal)
+    new_password = getpass.getpass("Enter new password for 'headquarter' user: ")
+    if not new_password:
+        print("Error: password cannot be empty.", file=sys.stderr)
+        sys.exit(1)
+
+    confirm = getpass.getpass("Confirm new password: ")
+    if new_password != confirm:
+        print("Error: passwords do not match.", file=sys.stderr)
+        sys.exit(1)
+
+    # Use psql inside the running postgres container to avoid exposing
+    # the password in host shell history.
+    sql = f"ALTER ROLE headquarter WITH PASSWORD '{new_password}';"
+
+    try:
+        result = subprocess.run(
+            [
+                "docker",
+                "exec",
+                "-i",
+                "hq-postgres",
+                "psql",
+                "-U",
+                "headquarter",
+                "-d",
+                "headquarter",
+                "-c",
+                sql,
+            ],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        print(result.stdout.strip())
+        print("\n✅ Password updated successfully.")
+        print("\n⚠️  IMPORTANT: Update your .env file:")
+        print(f"   POSTGRES_PASSWORD={new_password}")
+        print("\n⚠️  Then restart the application containers:")
+        print("   docker compose up -d")
+    except subprocess.CalledProcessError as exc:
+        print(f"Error: {exc.stderr or exc.stdout}", file=sys.stderr)
+        sys.exit(1)
+    except FileNotFoundError:
+        print(
+            "Error: 'docker' command not found. Is Docker installed and running?",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()