Repository navigation
Expand file tree
/
Copy pathdevctl.py
More file actions
executable file
·1560 lines (1311 loc) · 63.5 KB
/
Copy pathdevctl.py
File metadata and controls
executable file
·1560 lines (1311 loc) · 63.5 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
#!/usr/bin/env -S uv run
"""
Development process controller for TWICC.
Manages frontend (npm run dev) and backend (uv run ./run.py) processes
as independent background daemons with logging.
Data directory resolution:
1. In a git worktree: forced to the worktree root (PROJECT_ROOT)
2. TWICC_DATA_DIR environment variable (if set)
3. Default: ~/.twicc/
The .env file (ports, password hash, etc.) is read from the data directory.
The backend process receives TWICC_DATA_DIR so it uses the same paths.
"""
import glob
import hashlib
import os
import re
import shutil
import signal
import socket
import subprocess
import sys
import time
from pathlib import Path
# Paths
PROJECT_ROOT = Path(__file__).resolve().parent
DEVCTL_DIR = PROJECT_ROOT / ".devctl"
PIDS_DIR = DEVCTL_DIR / "pids"
# Default ports
DEFAULT_BACKEND_PORT = 3500
DEFAULT_FRONTEND_PORT = 5173
# How long `stop` waits for a process to exit on its own after SIGTERM before
# escalating to SIGKILL, and how long it then waits for the kill to take effect.
# The backend's graceful shutdown (agents, providers, db writer, search index)
# can take a few seconds; we must not return until it has released the data-dir
# lock, or a following `start` races it and loses (see stop() for the rationale).
STOP_GRACE_TIMEOUT = 10.0
STOP_KILL_TIMEOUT = 3.0
# Default data directory (same as twicc.paths)
DEFAULT_DATA_DIR = Path.home() / ".twicc"
TWICC_DATA_DIR_ENV = "TWICC_DATA_DIR"
def purge_claude_code_vars(env: dict) -> None:
"""Remove Claude Code environment variables from *env* in-place."""
for key in list(env):
if key.startswith(("CLAUDE_CODE", "CLAUDECODE")):
del env[key]
# Provider home variables honoured from the .env — the providers' official
# names, mirroring ``twicc.paths.PROVIDER_HOME_KEYS``. They are .env-exclusive:
# an inherited value is purged from the child environment and only the values
# the .env defines are re-added (``provider_home_env``), one layer before the
# backend applies the same rule, so it never even sees an inherited one.
# Design: docs/plans/2026-09-02-provider-home-dirs-design.md.
PROVIDER_HOME_KEYS = ("CLAUDE_CONFIG_DIR", "CLAUDE_SECURESTORAGE_CONFIG_DIR", "CODEX_HOME")
def purge_provider_home_vars(env: dict) -> None:
"""Remove the provider home variables (PROVIDER_HOME_KEYS) from *env* in-place."""
for key in PROVIDER_HOME_KEYS:
env.pop(key, None)
def provider_home_env(env_vars: dict[str, str]) -> dict[str, str]:
"""The provider home keys the .env defines (``env_vars`` from ``load_env_file``)."""
return {key: env_vars[key] for key in PROVIDER_HOME_KEYS if key in env_vars}
def describe_provider_homes(env_vars: dict[str, str]) -> list[str]:
"""One human line per provider home, mirroring ``twicc.provider_homes.describe_provider_homes``."""
home = Path.home()
claude = env_vars.get("CLAUDE_CONFIG_DIR")
lines = [
f"Claude Code home: {claude} (CLAUDE_CONFIG_DIR from .env)" if claude
else f"Claude Code home: {home / '.claude'} (default)"
]
secure = env_vars.get("CLAUDE_SECURESTORAGE_CONFIG_DIR")
if secure == "":
lines.append(f"Claude Code credentials: {home / '.claude'} (CLAUDE_SECURESTORAGE_CONFIG_DIR empty)")
elif secure:
lines.append(f"Claude Code credentials: {secure} (CLAUDE_SECURESTORAGE_CONFIG_DIR from .env)")
codex = env_vars.get("CODEX_HOME")
lines.append(
f"Codex home: {codex} (CODEX_HOME from .env)" if codex
else f"Codex home: {home / '.codex'} (default)"
)
return lines
def provider_home_line_warnings() -> list[str]:
"""Warn about .env lines for a provider home key that ``load_env_file`` (a plain
``KEY=VALUE`` parser) and the backend's python-dotenv would read differently:
an ``export`` prefix, ``${VAR}`` interpolation, an inline ``#`` comment."""
warnings: list[str] = []
if not ENV_FILE.exists():
return warnings
for raw in ENV_FILE.read_text().splitlines():
line = raw.strip()
if not line or line.startswith("#"):
continue
is_export = line.startswith("export ")
body = line[len("export "):] if is_export else line
key, _, value = body.partition("=")
key = key.strip()
if key not in PROVIDER_HOME_KEYS:
continue
problems = []
if is_export:
problems.append("'export ' prefix")
if "${" in value:
problems.append("'${...}' interpolation")
if "#" in value:
problems.append("inline '#' comment")
if problems:
warnings.append(
f"{key} in {ENV_FILE}: write it as a plain KEY=VALUE line "
f"({', '.join(problems)}: devctl and the backend would read different values)"
)
return warnings
def provider_home_hints(env_vars: dict[str, str]) -> list[str]:
"""Hint when a configured provider home looks unused (nothing logged in there yet).
Never an error, printed at every start until one of the files appears.
Codex: none of ``auth.json`` / ``config.toml`` / ``sessions/`` (Codex fills
``tmp/`` on its very first run, so "directory empty" is no signal; a
keyring-mode login implies a ``config.toml``). Claude: none of
``.credentials.json`` / ``settings.json`` / ``projects/``, skipped when the
credentials live elsewhere (``CLAUDE_SECURESTORAGE_CONFIG_DIR`` set).
"""
hints: list[str] = []
codex = env_vars.get("CODEX_HOME")
if codex and not any((Path(codex) / name).exists() for name in ("auth.json", "config.toml", "sessions")):
hints.append(f'CODEX_HOME={codex} looks unused: run "twicc codex login" from this instance\'s terminal')
claude = env_vars.get("CLAUDE_CONFIG_DIR")
if (
claude
and "CLAUDE_SECURESTORAGE_CONFIG_DIR" not in env_vars
and not any((Path(claude) / name).exists() for name in (".credentials.json", "settings.json", "projects"))
):
hints.append(f"CLAUDE_CONFIG_DIR={claude} looks unused: log in from a Claude session of this instance")
return hints
def print_provider_homes() -> None:
"""Print the provider homes + .env-line warnings + unused-home hints (start/status)."""
env_vars = load_env_file()
print("Provider homes:")
for line in describe_provider_homes(env_vars):
print(f" {line}")
for warning in provider_home_line_warnings():
print(f" Warning: {warning}")
for hint in provider_home_hints(env_vars):
print(f" Hint: {hint}")
def tmux_socket_suffix() -> str:
"""Per-data-dir tmux socket suffix — mirrors ``twicc.paths.tmux_socket_suffix``
standalone (same hash input ``str(data_dir.resolve())``, same default-dir
comparison; a test pins both to the same value)."""
data_dir = DATA_DIR.resolve()
if data_dir == DEFAULT_DATA_DIR.resolve():
return ""
return "-" + hashlib.sha256(str(data_dir).encode()).hexdigest()[:8]
def hybrid_enabled() -> bool:
"""Whether hybrid Claude CLI mode is on — mirrors ``settings.CLAUDE_HYBRID_ENABLED``.
Same truthy values as the backend, and the same precedence: the data dir's
``.env`` wins over the inherited environment. While off, the hybrid socket
is never used, so devctl neither names it nor kills it.
"""
key = "TWICC_CLAUDE_HYBRID_ENABLED"
value = load_env_file().get(key, os.environ.get(key, ""))
return value.strip().lower() in ("1", "true", "yes")
def tmux_socket_names() -> tuple[str, str]:
"""``(terminal socket, hybrid socket)`` of this instance (``terminal.py`` constants)."""
suffix = tmux_socket_suffix()
return "twicc" + suffix, "twicc-hybrid" + suffix
def kill_tmux() -> None:
"""``tmux -L <name> kill-server`` on the sockets this instance uses.
A suffixed tmux server outlives a deleted worktree (its terminals, any
surviving hybrid CLI): this is the cleanup. Refuses on the default data
dir, and is deliberately NOT part of ``stop`` — a tmux server must survive
a backend restart by design.
"""
if tmux_socket_suffix() == "":
print("Error: kill-tmux refuses to run on the default data dir (~/.twicc): "
"it would kill the main instance's tmux servers")
sys.exit(1)
tmux = shutil.which("tmux")
if tmux is None:
print("tmux is not installed, nothing to kill")
return
terminal_socket, hybrid_socket = tmux_socket_names()
for socket_name in [terminal_socket] + ([hybrid_socket] if hybrid_enabled() else []):
result = subprocess.run([tmux, "-L", socket_name, "kill-server"], capture_output=True)
outcome = "killed" if result.returncode == 0 else "no server running"
print(f" tmux -L {socket_name} kill-server: {outcome}")
def purge_foreign_venvs(env: dict) -> None:
"""Drop other projects' Python environments from *env* in-place.
devctl inherits the launching shell's environment and hands it to the
backend and the frontend — and, through the backend, to every agent
session. When that shell carries another project's ``.venv/bin`` on PATH,
a command missing from this project's venv resolves there instead: a
console script then starts that venv's interpreter, with its site-packages
and its editable install, so a tool run from this repo can silently import
another checkout's sources.
Only uv-style project venvs are dropped from PATH, and only foreign ones:
an entry qualifies when its parent directory is named ``.venv`` and holds
a ``pyvenv.cfg``. System dirs, ``~/.local/bin``, ``~/.cargo/bin`` and uv's
own tool venvs (``…/uv/tools/<tool>/bin``) keep their place and their
order. VIRTUAL_ENV is dropped when it points elsewhere; ``uv run`` sets
the right one for the backend.
PYTHONPATH goes altogether: it outranks every venv, and the backend has no
use for one — the editable install provides ``twicc``.
"""
own_venv = (PROJECT_ROOT / ".venv").resolve()
kept_path = []
for entry in env.get("PATH", "").split(os.pathsep):
venv = Path(entry).parent
foreign = (
bool(entry)
and venv.name == ".venv"
and (venv / "pyvenv.cfg").is_file()
and venv.resolve() != own_venv
)
if not foreign:
kept_path.append(entry)
env["PATH"] = os.pathsep.join(kept_path)
virtual_env = env.get("VIRTUAL_ENV")
if virtual_env and Path(virtual_env).resolve() != own_venv:
del env["VIRTUAL_ENV"]
env.pop("PYTHONPATH", None)
def is_git_worktree() -> bool:
"""Detect if we're running inside a git worktree (not the main working tree).
Compares git-dir (per-worktree) with git-common-dir (shared).
In the main worktree they resolve to the same path; in a secondary
worktree, git-dir points to .git/worktrees/<name>.
"""
try:
git_dir = subprocess.check_output(
["git", "rev-parse", "--git-dir"],
cwd=PROJECT_ROOT,
stderr=subprocess.DEVNULL,
).decode().strip()
common_dir = subprocess.check_output(
["git", "rev-parse", "--git-common-dir"],
cwd=PROJECT_ROOT,
stderr=subprocess.DEVNULL,
).decode().strip()
git_dir_resolved = os.path.realpath(os.path.join(str(PROJECT_ROOT), git_dir))
common_dir_resolved = os.path.realpath(os.path.join(str(PROJECT_ROOT), common_dir))
return git_dir_resolved != common_dir_resolved
except (subprocess.CalledProcessError, FileNotFoundError):
return False
def get_data_dir() -> Path:
"""Resolve the data directory for this devctl instance.
Priority:
1. Git worktree detected → PROJECT_ROOT (always forced, no override)
2. TWICC_DATA_DIR environment variable (if set)
3. Default → ~/.twicc/
"""
if is_git_worktree():
return PROJECT_ROOT
env_value = os.environ.get(TWICC_DATA_DIR_ENV, "").strip()
if env_value:
return Path(env_value).resolve()
return DEFAULT_DATA_DIR
# Resolve once at module level
DATA_DIR = get_data_dir()
ENV_FILE = DATA_DIR / ".env"
LOGS_DIR = DATA_DIR / "logs"
def find_available_port(start: int, max_attempts: int = 100) -> int:
"""Find an available port by incrementing from start.
Tries start, start+1, start+2, ... until a free port is found.
Raises RuntimeError if no port is available within max_attempts.
"""
for offset in range(max_attempts):
port = start + offset
if port > 65535:
break
try:
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
s.bind(("127.0.0.1", port))
return port
except OSError:
continue
raise RuntimeError(
f"Could not find an available port starting from {start} "
f"(tried {max_attempts} ports)"
)
def save_worktree_env(backend_port: int, frontend_port: int) -> None:
"""Append the worktree configuration to the .env file in the data directory.
The ports, plus the opt-out of the backend's startup log trim: a worktree
log is short-lived, keeping it bounded is pointless work.
"""
lines_to_add = [
"",
"# Auto-configured by devctl (worktree mode)",
f"TWICC_PORT={backend_port}",
f"VITE_PORT={frontend_port}",
"# No startup trim of logs/backend.log in a worktree",
"TWICC_NO_LOG_TRIM=1",
"",
]
with open(ENV_FILE, "a") as f:
f.write("\n".join(lines_to_add))
def save_fresh_provider_homes_env(claude_home: Path, codex_home: Path) -> None:
"""Append the fresh provider homes to the data dir's .env (``--fresh-providers``).
``CLAUDE_SECURESTORAGE_CONFIG_DIR`` is written EMPTY on purpose — the
documented way to keep the real credentials next to a relocated
``CLAUDE_CONFIG_DIR``. The rationale goes on its own comment line: an
inline ``#`` on a provider-home line is exactly what
``provider_home_line_warnings`` flags.
"""
lines_to_add = [
"",
"# Auto-configured by devctl (--fresh-providers): empty homes, no history to re-scan",
f"CLAUDE_CONFIG_DIR={claude_home}",
"# Empty: keep the real ~/.claude credentials (no re-login, no keychain rename)",
"CLAUDE_SECURESTORAGE_CONFIG_DIR=",
f"CODEX_HOME={codex_home}",
"",
]
with open(ENV_FILE, "a") as f:
f.write("\n".join(lines_to_add))
def save_worktree_catalog_env(values: dict[str, str], origins: dict[str, str]) -> None:
"""Append catalogue values to the data dir's .env (see :func:`apply_worktree_env_catalog`).
``origins`` maps a key to the catalogue file it came from, so the .env says
where a surprising line was picked up. On its own comment line: an inline
``#`` on a provider-home line is what ``provider_home_line_warnings`` flags.
"""
lines_to_add = ["", f"# Auto-configured by devctl from {WORKTREE_ENV_DIR_NAME}/"]
for key in sorted(values):
lines_to_add.append(f"# from {origins[key]}")
lines_to_add.append(f"{key}={values[key]}")
lines_to_add.append("")
with open(ENV_FILE, "a") as f:
f.write("\n".join(lines_to_add))
# User preference files carried into a worktree's data dir alongside the DB.
# Infra (.env), logs/, and drop-requests/ are deliberately excluded.
SYNCED_CONFIG_FILENAMES = (
"settings.json",
"workspaces.json",
"layouts.json",
"terminal-config.json",
"message-snippets.json",
"tts.json",
"seen-tips.json",
"seen-help.json",
"providers-status.json",
)
SYNCED_CONFIG_GLOBS = ("*-settings-presets.json",)
# Data-dir subdirectories shared with the main data dir via symlink in worktree
# mode (see link_shared_dirs_from_main): per-session artifacts and scratch live
# under the main data dir so a worktree instance reads/writes the same files.
SHARED_LINK_DIRS = ("artifacts", "scratch")
# Where ``--fresh-providers`` puts the worktree's own provider homes: inside its
# data dir, next to db/ and logs/ (and gitignored with them), so deleting the
# worktree takes them along.
PROVIDER_HOMES_DIR_NAME = "provider-homes"
# Codex files carried into a fresh CODEX_HOME. Never sessions/ — not re-scanning
# that history is the whole point. Codex creates everything else on first run.
CODEX_SEED_FILENAMES = ("auth.json", "config.toml")
# Catalogue of .env values to pre-fill in a worktree, kept in the MAIN repo next
# to .worktrees/ (and gitignored with it) so it survives every worktree.
# ``default.env`` holds what every worktree shares (typically the password
# hash); ``<vite port>.env`` holds what follows one tunnel (its hostname).
WORKTREE_ENV_DIR_NAME = ".worktrees-env"
WORKTREE_ENV_DEFAULT_FILE = "default.env"
# Keys the catalogue may not set. Each has a concrete failure mode, so this is
# a deny-list, not a taste call — everything else passes, with no maintenance
# when a new key becomes worth pre-filling:
# • TWICC_PORT / VITE_PORT — devctl writes them from the port search, which
# runs BEFORE the catalogue (the port IS the index). A catalogue line would
# only contradict them, and devctl reads the FIRST occurrence of a key while
# the backend's python-dotenv reads the LAST: the two would disagree on the
# port.
# • TWICC_NO_LOG_TRIM — devctl writes it too.
# • TWICC_DATA_DIR — read ONLY from the environment by design (it locates the
# .env), so in a .env it is inert and misleading.
WORKTREE_ENV_REFUSED_KEYS = ("TWICC_PORT", "VITE_PORT", "TWICC_NO_LOG_TRIM", TWICC_DATA_DIR_ENV)
def synced_config_files(base_dir: Path) -> list[Path]:
"""Resolve the user preference files present at the root of base_dir.
Fixed config files plus the per-provider *-settings-presets.json bundles.
Returns only files that actually exist, so the result is usable both as the
copy source list (from the main data dir) and the clear list (from the
worktree data dir).
"""
files = [base_dir / name for name in SYNCED_CONFIG_FILENAMES]
for pattern in SYNCED_CONFIG_GLOBS:
files.extend(sorted(base_dir.glob(pattern)))
return [path for path in files if path.exists()]
def copy_data_from_main() -> bool:
"""Copy the database, search index and user config from the main data directory to the worktree.
Copies data.sqlite as a consistent snapshot (SQLite's online backup API,
in one step under a read lock — a plain file copy of the database plus
its WAL/SHM while the main instance keeps writing produces a torn,
"malformed" copy), the search-index/ directory, the project-icons/
directory, the user preference files (settings, workspaces, presets,
snippets, tips) and the per-install secret-key.
Only called in worktree mode when the local database doesn't exist yet, so
everything lands together on first setup. Existing local files are never
overwritten.
Returns True if the copy succeeded (or source doesn't exist), False on error.
"""
source_db = DEFAULT_DATA_DIR / "db" / "data.sqlite"
target_db_dir = DATA_DIR / "db"
target_db = target_db_dir / "data.sqlite"
if target_db.exists():
return True # Already have local data
if not source_db.exists():
print(" No main database found, starting fresh")
return True # No source to copy, Django migrate will create it
# Copy database
print(f" Copying database from {source_db.parent}...", end=" ", flush=True)
# Ensure target directory exists
target_db_dir.mkdir(parents=True, exist_ok=True)
# Snapshot data.sqlite with the backup API. The WAL/SHM files are not
# copied: the snapshot already folds in every committed transaction, and
# a stray WAL from another process would only corrupt it. ``pages=-1``
# copies everything in one step — a stepped backup restarts from zero
# whenever the source is written to in between, which on a busy main
# instance can take many times longer than the copy itself.
import sqlite3
try:
source = sqlite3.connect(f"file:{source_db}?mode=ro", uri=True)
try:
target = sqlite3.connect(str(target_db))
try:
source.backup(target, pages=-1)
finally:
target.close()
finally:
source.close()
except sqlite3.Error as e:
print("FAILED")
print(f" {e}")
for leftover in (target_db, Path(f"{target_db}-journal")):
if leftover.exists():
leftover.unlink()
return False
copied_files = ["data.sqlite (snapshot)"]
print("OK")
print(f" Files: {', '.join(copied_files)}")
# Copy search index (if it exists in the main data dir)
source_search = DEFAULT_DATA_DIR / "search-index"
target_search = DATA_DIR / "search-index"
if source_search.exists() and not target_search.exists():
print(f" Copying search index from {source_search}...", end=" ", flush=True)
shutil.copytree(source_search, target_search)
print("OK")
# Copy project icons. The copied database carries each project's icon state
# (a manual override names a file under its proj-<hash> bucket), so without
# the files the worktree serves a 404 for every manual icon. Auto-discovery
# only ever rebuilds the repo-<hash> buckets, never the overrides.
source_icons = DEFAULT_DATA_DIR / "project-icons"
target_icons = DATA_DIR / "project-icons"
if source_icons.exists() and not target_icons.exists():
print(f" Copying project icons from {source_icons}...", end=" ", flush=True)
shutil.copytree(source_icons, target_icons)
print("OK")
# Copy user preference files (settings, workspaces, presets, snippets, tips).
# Same one-shot timing as the DB — we only reach here on first worktree
# setup (guarded by the target_db.exists() check above). A file the worktree
# already has is left untouched, so local divergence is preserved.
copied_config = []
for source_file in synced_config_files(DEFAULT_DATA_DIR):
target_file = DATA_DIR / source_file.name
if not target_file.exists():
shutil.copy2(source_file, target_file)
copied_config.append(source_file.name)
if copied_config:
print(f" Copied config files: {', '.join(copied_config)}")
# Copy the per-install SECRET_KEY so the Django sessions carried over in
# the copied database stay valid in the worktree (same signing key).
source_secret = DEFAULT_DATA_DIR / "secret-key"
target_secret = DATA_DIR / "secret-key"
if source_secret.exists() and not target_secret.exists():
shutil.copy2(source_secret, target_secret)
print(" Copied secret-key")
return True
def link_shared_dirs_from_main() -> None:
"""Symlink the artifacts/ and scratch/ dirs to the main data directory.
In worktree mode, point ``<worktree>/artifacts`` and ``<worktree>/scratch``
at the main data dir's equivalents so a worktree instance shares the very
same per-session artifacts and scratch files as the primary instance (a
session's Artifacts tab then works in the worktree without copying gigabytes
of screenshots). Paired with ``copy_data_from_main`` — i.e. NOT under
``--empty-db``, which keeps the worktree fully isolated.
Idempotent and conservative: only creates a link when the worktree path is
absent (never clobbers an existing real dir or link), and ensures the
main-side target exists first so the link is never dangling.
"""
if DATA_DIR == DEFAULT_DATA_DIR:
return # Not a worktree — main instance owns these dirs directly
for name in SHARED_LINK_DIRS:
target = DATA_DIR / name # <worktree>/artifacts
# is_symlink() catches a broken link (exists() is False for those).
if target.exists() or target.is_symlink():
continue # Leave an existing real dir or link untouched
source = DEFAULT_DATA_DIR / name # ~/.twicc/artifacts
source.mkdir(parents=True, exist_ok=True) # never leave the link dangling
os.symlink(source, target, target_is_directory=True)
print(f" Linked {name}/ -> {source}")
def clear_local_data() -> None:
"""Delete the local database, search index and user config in the worktree.
Removes data.sqlite and any WAL/SHM files, the search-index/ directory, the
project-icons/ directory, the user preference files (settings, workspaces,
presets, snippets, tips) and the per-install secret-key, so the next start
creates a fresh empty database, rebuilds the search index, rediscovers the
icons, and carries no config or key over from the main data directory.
"""
# Clear database
target_db = DATA_DIR / "db" / "data.sqlite"
if target_db.exists():
removed_files = []
for db_file in glob.glob(str(target_db) + "*"):
os.remove(db_file)
removed_files.append(os.path.basename(db_file))
print(f" Cleared local database: {', '.join(removed_files)}")
# Clear search index
target_search = DATA_DIR / "search-index"
if target_search.exists():
shutil.rmtree(target_search)
print(" Cleared local search index")
# Clear project icons — the fresh database has no manual override left, and
# auto-discovery rebuilds the repo buckets on the first scan.
target_icons = DATA_DIR / "project-icons"
if target_icons.exists():
shutil.rmtree(target_icons)
print(" Cleared local project icons")
# Clear user preference files (settings, workspaces, presets, snippets, tips).
removed_config = []
for config_file in synced_config_files(DATA_DIR):
os.remove(config_file)
removed_config.append(config_file.name)
if removed_config:
print(f" Cleared config files: {', '.join(removed_config)}")
# Clear the per-install SECRET_KEY so the isolated instance generates its
# own instead of sharing the main install's signing key.
target_secret = DATA_DIR / "secret-key"
if target_secret.exists():
os.remove(target_secret)
print(" Cleared secret-key")
# Remove shared-dir symlinks (artifacts/, scratch/) so the fresh start gets
# isolated local dirs. Only unlink a symlink — never delete a real directory
# or the shared target's contents.
for name in SHARED_LINK_DIRS:
target = DATA_DIR / name
if target.is_symlink():
target.unlink()
print(f" Unlinked {name}/ (was shared with main)")
def main_repo_root() -> Path | None:
"""Root of the MAIN working tree, resolved from this (possibly worktree) checkout.
``git rev-parse --git-common-dir`` points at the ``.git`` shared by every
worktree — i.e. the main working tree's — whatever checkout asks; its parent
is that tree's root. ``None`` when git is unavailable or this is not a
repository. Resolved rather than assumed: a worktree need not live under
``.worktrees/``, so no relative path can be hardcoded.
"""
try:
common_dir = subprocess.check_output(
["git", "rev-parse", "--git-common-dir"],
cwd=PROJECT_ROOT,
stderr=subprocess.DEVNULL,
).decode().strip()
except (subprocess.CalledProcessError, FileNotFoundError):
return None
return Path(os.path.realpath(os.path.join(str(PROJECT_ROOT), common_dir))).parent
def apply_worktree_env_catalog(frontend_port: int) -> None:
"""Pre-fill this worktree's .env from the main repo's ``.worktrees-env/``.
Reads ``default.env``, then ``<frontend_port>.env`` which wins, and appends
every key the worktree's .env does not already define. Typical content: the
password hash in ``default.env`` (portable as-is — the stored string carries
its own salt and iterations), the tunnel's ``TWICC_DEV_HOSTNAME`` in the
per-port file.
Indexed on the VITE port because that is how a worktree is reached — through
the dev server, so HMR works — and because it is the port devctl actually
retained: a worktree pushed to 5175 by a busy 5174 gets 5175's tunnel, which
is what a tunnel bound to a port should do.
Never overwrites: a value already in the .env wins, as with
:func:`setup_fresh_provider_homes`. A no-op when the directory is absent.
"""
repo_root = main_repo_root()
if repo_root is None:
return
catalog_dir = repo_root / WORKTREE_ENV_DIR_NAME
if not catalog_dir.is_dir():
return
# Per-port last so it wins; ``origins`` keeps the provenance for the .env
# comments and the summary line below.
values: dict[str, str] = {}
origins: dict[str, str] = {}
for name in (WORKTREE_ENV_DEFAULT_FILE, f"{frontend_port}.env"):
source = catalog_dir / name
if not source.is_file():
continue
for key, value in load_env_file(source).items():
values[key] = value
origins[key] = f"{WORKTREE_ENV_DIR_NAME}/{name}"
refused = sorted(set(values) & set(WORKTREE_ENV_REFUSED_KEYS))
for key in refused:
print(f" Ignored {key} from {origins[key]}: devctl owns this key")
del values[key]
# Report only a real divergence. Every key applied on a past start is now in
# the .env with the very same value, so reporting equality would print a
# line on every restart forever.
existing = load_env_file()
diverging = sorted(k for k in set(values) & set(existing) if existing[k] != values[k])
for key in set(values) & set(existing):
del values[key]
if diverging:
print(f" Kept the .env's own {', '.join(diverging)} over {WORKTREE_ENV_DIR_NAME}/")
if not values:
return
save_worktree_catalog_env(values, origins)
print(f" Applied {', '.join(sorted(values))} from {WORKTREE_ENV_DIR_NAME}/ (vite port {frontend_port})")
def main_instance_codex_home() -> Path:
"""Where the developer's real Codex login lives.
The main data dir's ``.env`` may relocate ``CODEX_HOME``; otherwise it is
the CLI's default ``~/.codex``. Claude needs no equivalent: an empty
``CLAUDE_SECURESTORAGE_CONFIG_DIR`` always resolves to ``~/.claude``
(``twicc.provider_homes.claude_secure_storage_dir``).
"""
configured = load_env_file(DEFAULT_DATA_DIR / ".env").get("CODEX_HOME")
return Path(configured) if configured else Path.home() / ".codex"
def setup_fresh_provider_homes() -> None:
"""Point this worktree at its own provider homes, with no session history.
The initial sync of a worktree instance otherwise re-scans the developer's
real homes — hundreds of MB under ``~/.claude/projects``, GB under
``~/.codex/sessions``. Relocating both homes to empty directories skips
that, and keeps the worktree's own sessions out of the real homes.
Logins are preserved, never re-done:
- Claude: ``CLAUDE_SECURESTORAGE_CONFIG_DIR`` is written EMPTY, which
resolves to ``~/.claude``, so the real ``.credentials.json`` stays
shared and the macOS keychain service name is left alone (relocating the
credentials dir suffixes it, which would force a re-login).
- Codex has no such split — ``auth.json`` lives in ``CODEX_HOME`` — so the
login and config files are copied.
Idempotent and conservative: a ``.env`` that already configures any
provider home is left untouched, so a manual value always wins.
"""
configured = provider_home_env(load_env_file())
if configured:
print(f" Provider homes already in .env ({', '.join(sorted(configured))}), left as is")
return
homes_dir = DATA_DIR / PROVIDER_HOMES_DIR_NAME
claude_home = homes_dir / "claude"
codex_home = homes_dir / "codex"
for path in (claude_home, codex_home):
path.mkdir(parents=True, exist_ok=True)
path.chmod(0o700)
source_codex = main_instance_codex_home()
copied, missing = [], []
for name in CODEX_SEED_FILENAMES:
source = source_codex / name
if source.is_file():
shutil.copy2(source, codex_home / name)
copied.append(name)
else:
missing.append(name)
if copied:
print(f" Seeded Codex home from {source_codex}: {', '.join(copied)}")
if missing:
print(
f' Warning: no {", ".join(missing)} in {source_codex} — '
'run "twicc codex login" from this instance'
)
save_fresh_provider_homes_env(claude_home, codex_home)
print(f" Fresh provider homes under {homes_dir}, saved to {ENV_FILE}")
def load_env_file(path: Path | None = None) -> dict[str, str]:
"""Load environment variables from a .env file (the data directory's by default)."""
env_vars = {}
env_file = ENV_FILE if path is None else path
if env_file.exists():
with open(env_file) as f:
for line in f:
line = line.strip()
# Skip empty lines and comments
if not line or line.startswith("#"):
continue
# Parse KEY=VALUE (strip optional quotes around value)
if "=" in line:
key, _, value = line.partition("=")
value = value.strip()
if len(value) >= 2 and value[0] == value[-1] and value[0] in ('"', "'"):
value = value[1:-1]
env_vars[key.strip()] = value
return env_vars
def get_ports(auto_find: bool = False) -> tuple[int, int]:
"""Get backend and frontend ports from .env file or defaults.
If auto_find is True and we're in a worktree, automatically find
available ports (incrementing from defaults) and save them to .env.
This avoids port conflicts when running multiple worktrees.
"""
env_vars = load_env_file()
backend_port = DEFAULT_BACKEND_PORT
frontend_port = DEFAULT_FRONTEND_PORT
has_backend_port = "TWICC_PORT" in env_vars
has_frontend_port = "VITE_PORT" in env_vars
if has_backend_port:
try:
backend_port = int(env_vars["TWICC_PORT"])
except ValueError:
print(f"Warning: Invalid TWICC_PORT in .env, using default {DEFAULT_BACKEND_PORT}")
if has_frontend_port:
try:
frontend_port = int(env_vars["VITE_PORT"])
except ValueError:
print(f"Warning: Invalid VITE_PORT in .env, using default {DEFAULT_FRONTEND_PORT}")
# In worktree mode, auto-find available ports if not already configured
if auto_find and is_git_worktree() and (not has_backend_port or not has_frontend_port):
if not has_backend_port:
backend_port = find_available_port(DEFAULT_BACKEND_PORT + 1)
if not has_frontend_port:
frontend_port = find_available_port(DEFAULT_FRONTEND_PORT + 1)
save_worktree_env(backend_port, frontend_port)
print(f" Auto-configured ports for worktree: backend={backend_port}, frontend={frontend_port}")
print(f" Saved to {ENV_FILE}")
return backend_port, frontend_port
def get_process_config(backend_port: int, frontend_port: int) -> dict:
"""Build process configuration with the given port settings."""
env_vars = load_env_file()
dev_hostname = env_vars.get("TWICC_DEV_HOSTNAME", "")
frontend_env = {
"BACKEND_PORT": str(backend_port),
}
if dev_hostname:
frontend_env["DEV_HOSTNAME"] = dev_hostname
return {
"front": {
"name": "Frontend (Vite)",
"cmd": ["npm", "run", "dev", "--", "--port", str(frontend_port)],
"cwd": PROJECT_ROOT / "frontend",
"log": LOGS_DIR / "frontend.log",
"pid": PIDS_DIR / "frontend.pid",
"port": frontend_port,
"env": frontend_env,
},
"back": {
"name": "Backend (Django)",
"cmd": ["uv", "run", "./run.py"],
"cwd": PROJECT_ROOT,
"log": LOGS_DIR / "backend.log",
"pid": PIDS_DIR / "backend.pid",
"port": backend_port,
"env": {
"TWICC_PORT": str(backend_port),
TWICC_DATA_DIR_ENV: str(DATA_DIR),
"TWICC_DEBUG": "1",
# In worktree mode:
# - Use a distinct session cookie name to avoid conflicts with the main instance
# (browsers share cookies across ports).
# - Disable cron auto-restart (worktrees are for development, not for running
# persistent cron jobs from previous sessions).
# - Auto-enable every registered provider: at backend boot, if settings.json has
# no ``disabledProviders`` key yet, seed it with an empty list so the activation
# dialog never opens and the orchestrators start immediately. After that one-shot
# seed, toggles from Settings keep working normally.
# - Skip the Codex marketplace + plugin install when the worktree shares the
# default ~/.codex (its config.toml is already managed by the main install —
# worktrees must not race on it). A worktree whose .env sets its own
# CODEX_HOME installs its own copy of the plugin there; that is the point.
# - Disable the empty-session-dirs janitor: artifacts/ and scratch/ are symlinks
# shared with the main instance, which owns the cleanup (a worktree would
# otherwise prune the shared dirs based on its own, partial DB).
# - The tmux reaper stays ON: the tmux sockets are per data dir (see
# tmux_socket_suffix), so a worktree only ever sees its own sessions.
# - Initialize the telemetry setting to OFF once: dev worktrees are
# throwaway instances. Users can enable it in Settings afterwards.
# - Never prune old Codex runtimes: ~/.cache/twicc/codex-runtime/ is shared
# with the main instance, and a worktree bumping CODEX_VERSION would delete
# the version that instance is running on. It still downloads its own.
# - Default the tips toggle to OFF: agents drive the worktree UI to inspect
# their work, and a tip toast popping over it disturbs them. A browser
# that already chose (Settings > Tips) keeps its choice.
# - Let a DIRECT LOOPBACK request past the instance password: a worktree's
# database dies with the checkout, so its login session never survives a
# re-creation, and an agent that starts one has no reason to know the
# user's password. Remote access is untouched — the backend only grants
# this when the data dir really is a git worktree AND the request carries
# no forwarding header, so the same instance reached through its tunnel
# keeps asking (see twicc.auth.access).
**({
"TWICC_SESSION_COOKIE": f"sessionid_{backend_port}",
"TWICC_DEV_LOCAL_BYPASS": "1",
"TWICC_NO_CRON_RESTART": "1",
"TWICC_AUTO_ENABLE_PROVIDERS": "1",
**({"TWICC_NO_CODEX_PLUGIN": "1"} if "CODEX_HOME" not in load_env_file() else {}),
"TWICC_NO_SESSION_DIRS_CLEANUP": "1",
"TWICC_NO_TELEMETRY": "1",
"TWICC_NO_CODEX_RUNTIME_CLEANUP": "1",
"TWICC_TIPS_DEFAULT_OFF": "1",
} if is_git_worktree() else {}),
},
},
}
def build_process_env(config: dict) -> dict[str, str]:
"""The environment handed to a child process: the inherited one, purged, plus the config's."""
proc_env = os.environ.copy()
# Purge Claude Code environment variables so the backend/frontend processes
# don't inherit them (e.g., when devctl is launched from within Claude Code).
# CLAUDE_CODE_ENTRYPOINT in particular causes Claude Code to think it's
# already running inside an SDK session, preventing interactive use.
purge_claude_code_vars(proc_env)
# Provider homes are .env-exclusive (all modes): drop any inherited
# CLAUDE_CONFIG_DIR / CLAUDE_SECURESTORAGE_CONFIG_DIR / CODEX_HOME, then
# re-add below only what this data dir's .env defines. A worktree started
# from an agent session of another instance must never inherit that
# instance's homes.
purge_provider_home_vars(proc_env)
# Drop any other project's virtualenv from the inherited environment, so a
# command missing from this project's venv can never resolve to another
# checkout's (see purge_foreign_venvs).
purge_foreign_venvs(proc_env)
# In worktree mode, purge inherited TWICC_* variables so the child
# process only sees values from the worktree's .env (loaded by run.py).
# Without this, variables like TWICC_PASSWORD_HASH from the parent
# shell would leak into the backend and override the worktree config.
if is_git_worktree():
for key in list(proc_env):
if key.startswith("TWICC_"):
del proc_env[key]
if "env" in config:
proc_env.update(config["env"])
proc_env.update(provider_home_env(load_env_file()))
return proc_env
def ensure_dirs():
"""Create directory structure for PIDs and logs."""
PIDS_DIR.mkdir(parents=True, exist_ok=True)
LOGS_DIR.mkdir(parents=True, exist_ok=True)
def is_running(proc_key: str, processes: dict) -> tuple[bool, int | None]:
"""Check if a process is running. Returns (is_running, pid)."""
pid_file = processes[proc_key]["pid"]
if not pid_file.exists():
return False, None
pid = int(pid_file.read_text().strip())
try:
os.kill(pid, 0) # Signal 0 just checks if process exists
return True, pid
except OSError:
# Process doesn't exist, clean up stale pid file
pid_file.unlink()
return False, None
def _pid_alive(pid: int) -> bool:
"""Return True if *pid* still exists (signal 0 probe, no signal delivered)."""
try:
os.kill(pid, 0)
return True
except OSError:
return False
def wait_for_exit(pid: int, timeout: float) -> bool:
"""Poll until *pid* is gone or *timeout* seconds elapse.
devctl is not the process's parent (a previous invocation detached it via
start_new_session), so we can't waitpid() it — we probe liveness with
signal 0. Returns True if the process exited within the timeout.
"""
deadline = time.time() + timeout
while time.time() < deadline:
if not _pid_alive(pid):
return True
time.sleep(0.1)
return not _pid_alive(pid)