Task Tracker

Персональная Windows-служба для папок задач и снимков проектов. Служба выполняет Python-код из защищённого каталога Tracker; плагины Codex подключаются к её локальному MCP endpoint.

Требования

• Windows и права администратора. Bootstrap и установка службы запускаются в повышенной PowerShell; целевой пользователь и сервисная учётная запись должны быть разными.
• PowerShell 7 и Git. pwsh выполняет сценарии, git проверяет клон. Репозиторий task-tracker должен быть на чистой main, совпадающей с локальной origin/main.
• Доступ установщика к checkout. Учётной записи установщика нужны права чтения локального репозитория. Git получает доверие только к точному пути checkout на время каждой проверки; глобальная Git-конфигурация и ACL файлов не меняются.
• Python и пакеты. Установленные Windows launcher py.exe, требуемая версия Python с venv и pip, доступный источник пакетов для установки PyYAML. Установщик создаёт отдельный защищённый venv; Python сам не скачивает.
• Компилятор .NET Framework 4. csc.exe из Windows нужен при сборке или пересборке ядра службы.
• Node.js и Codex Desktop. Node запускает MCP-клиенты двух плагинов; целевой пользователь устанавливает их в Codex самостоятельно.

Настраиваемое окружение

• -TargetUser. Обязательное имя пользователя Windows, для которого работает Tracker, например DOMAIN\User. Bootstrap читает профиль именно этого пользователя, даже если администратор вошёл под другой учётной записью.
• <профиль TargetUser>\.env\env.txt. Обычный UTF-8 файл, создаваемый пользователем до первого запуска. В нём нужна ровно одна запись TRACKER_FOLDER=<абсолютный выделенный каталог Tracker> и одна GIT_FOLDER=<существующий абсолютный корень проектов, например C:\Git>.
• GIT_FOLDER. При установке и переустановке без -SnapshotRoots становится разрешённым корнем снимков в service.json.
• TRACKER_MCP_TOKEN. Вручную не задаётся: первая установка создаёт его в пользовательском env.txt и защищённом Tracker; переустановка сверяет и сохраняет обе копии.
• .venv/python_version.txt и requirements.txt. Версионируемые настройки Python и пакетов. Сейчас задан python3.11 и PyYAML==6.0.3; при отсутствии этой версии установка останавливается без fallback.
• -SnapshotRoots, -ServiceAccountName, -TrustAuthenticatedUsers. Необязательные параметры bootstrap: первый явно задаёт один или несколько корней снимков, второй — имя сервисной учётной записи, третий допускает широкий доступ к родительскому каталогу Tracker только при сознательном доверии этим пользователям.

Краткая схема установки

Из корня репозитория в повышенной PowerShell:

pwsh -NoProfile -File .\bootstrap.ps1 -TargetUser 'DOMAIN\User'

Корневой bootstrap.ps1 — единый вход: имя целевого пользователя задаётся один раз в аргументе -TargetUser, редактировать файл не нужно. Он проверяет Git, готовит защищённый корень, создаёт bootstrap.json и административный wrapper, затем сам запускает wrapper для установки или обновления службы. Для второй службы укажите свободный порт через -McpPort (например, 38773); повторная установка сохраняет установленный порт. При установке и переустановке GIT_FOLDER задаёт корень снимков в service.json; явный -SnapshotRoots переопределяет его. Для допустимого Modify на родителе дополнительный флаг не нужен; -TrustAuthenticatedUsers требуется лишь при более широких правах, которые администратор осознанно принимает. Владельца существующего Tracker скрипты не меняют.

Установщик не меняет плагины Codex и не запрашивает пароль целевого пользователя. Сообщение об успешной установке подтверждает службу, но не наличие MCP-инструментов в Codex: состояние плагинов не входит в проверки и откат установщика. В профиле TargetUser проверьте ai-marketplace из https://github.com/twilight-slider/ai-marketplace.git и включённые task-folder-workflow@ai-marketplace 0.6.2 и task-tracker-mcp@ai-marketplace 0.2.2. Если их нет, пользователь устанавливает их самостоятельно через Codex; после изменения плагинов полностью перезапустите Codex. Плагины сами читают TRACKER_MCP_TOKEN и TRACKER_MCP_PORT из пользовательского env.txt; отдельный файл запуска Codex не нужен.

Подробности: административный bootstrap, установка v3.

Схема прав

• Родительский каталог Tracker принадлежит Administrators или SYSTEM. Другим учётным записям разрешён Modify, если он не сопровождается правами удаления дочерних объектов (DeleteSubdirectoriesAndFiles), смены ACL или владельца. Tracker не наследует права родителя. -TrustAuthenticatedUsers допускает и более широкие права родителя только при сознательном доверии этим пользователям.
• Корень Tracker имеет независимый ACL. Допустимый владелец — Administrators, SYSTEM или фактическая сервисная учётная запись; последняя входит в доверенный перечень владельцев и получает полный доступ. Целевой пользователь получает только чтение и проход по каталогам, без записи, удаления и изменения прав. Владельца существующего Tracker bootstrap не меняет. В корне находятся только каталоги tasks, .protected и файл projects.json.
• projects.json доступен целевому пользователю только на чтение. Служба изменяет его при регистрации проектов и создании локальных задач.
• .protected не наследует ACL. Полный доступ имеют администраторы, SYSTEM и сервисная учётная запись; целевой пользователь не получает права менять служебный код, runtime, конфигурацию и защищённую копию токена. Сервисная учётная запись должна отличаться от целевого пользователя и не быть администратором.
• Папки задач создаёт служба. На tasks и годовых каталогах целевой пользователь может только читать и проходить; файлы он меняет внутри каталога конкретной задачи, кроме .protected и его потомков. Каталоги задач и защищённые подпапки он удалять и переименовывать не может. Инструкции AGENTS.md лежат в tasks и доступны только на чтение. Вторая копия MCP-токена хранится в пользовательском .env\env.txt; доступ к этому файлу следует ограничить владельцем профиля.

Что проверяют скрипты

1. Корневой bootstrap требует повышенную PowerShell, чистую ветку main и равенство HEAD локальному origin/main; сетевой fetch он не делает.
2. По -TargetUser определяется SID и профиль. Проверяются обычный файл .env\env.txt, ровно один абсолютный TRACKER_FOLDER; без -SnapshotRoots — ровно один существующий абсолютный GIT_FOLDER. Корни снимков должны существовать, быть обычными каталогами и не пересекаться с Tracker.
3. Подготовка проверяет владельца и ACL родителя, корня и .protected; существующего владельца не меняет. Bootstrap сверяет SID установленной службы, сервисную учётную запись и защищённые файлы, затем создаёт bootstrap.json и wrapper.
4. Защищённый wrapper повторяет проверки Git, SID, путей, владельцев и ACL. Установщик проверяет Python заданной версии, venv, pip и PyYAML, обе копии MCP-токена и привязку существующей службы до переключения файлов. Компилятор C# проверяется только при первой сборке или изменении исходника host.
5. После установки проверяются статус службы Running/Automatic и авторизованный MCP-запрос. Плагины Codex проверяет и устанавливает сам целевой пользователь. При сбое установки выполняется откат; незавершённый откат помечается RECOVERY_INCOMPLETE.

Для отдельной проверки двух установленных служб запустите tests/integration-two-services.ps1 под каждым из двух обычных пользователей, передав -OtherServiceName и -OtherPort второй службы. Тест проверяет запуск обеих служб, свой и чужой MCP endpoint, свой и чужой named pipe; токены не выводит. В обычной установке с одной службой этот тест не запускается.

Ошибки установки и исправление

Здесь перечислены предусмотренные скриптами группы отказов. Начала сообщений приведены без машинных путей и SID; сообщения с одинаковым исправлением объединены. Системные ошибки Windows, Git, pip и Codex сохраняют свой исходный текст.

Сообщение или признак	Что исправить
Run this TaskTracker step from an elevated PowerShell window	Запустить PowerShell от администратора.
Specify -TargetUser; Cannot resolve TargetUser; TargetUser profile is invalid	Передать существующее имя DOMAIN\User; убедиться, что у пользователя создан профиль.
TargetUser env file is missing; env file must be plain	Создать обычный <профиль>\.env\env.txt, не ссылку, доступный для чтения администратору.
exactly one TRACKER_FOLDER; TRACKER_FOLDER must be an absolute path; cannot be a volume root	Оставить одну запись TRACKER_FOLDER=<абсолютный выделенный каталог>; не указывать корень диска.
exactly one GIT_FOLDER; GIT_FOLDER must be an absolute path	Добавить одну запись GIT_FOLDER=<существующий абсолютный корень проектов>, например C:\Git, либо явно передать -SnapshotRoots.
SnapshotRoots cannot be empty; At least one snapshot root is required; Bootstrap JSON must specify at least one snapshot root	Задать GIT_FOLDER или непустой -SnapshotRoots.
Directory path must be absolute; contains a file or reparse point; Snapshot root must be separate from Tracker storage	Указать существующий обычный каталог абсолютным путём; не использовать ссылку и не пересекать его с Tracker.
Git check failed; checkout root differs; checkout must be on main; HEAD differs from local origin/main	Проверить доступ к клону и его путь, перейти на main, синхронизировать его с локальным origin/main. Временное доверие checkout передаётся только текущей команде Git; глобальная конфигурация не меняется.
checkout has staged, unstaged or untracked changes; Checkout commit differs from bootstrap JSON	Закоммитить или убрать изменения; после нового commit повторно запустить корневой bootstrap.
Choose a dedicated Tracker path; TRACKER_FOLDER is inside a user/system directory	Выбрать отдельный каталог Tracker под выделенным родителем, вне профиля пользователя, системных каталогов и корня диска.
Tracker parent is not administrator-owned; parent permits untrusted delete/ACL rights	Родитель должен принадлежать Administrators/SYSTEM. Modify допустим, но удаление дочерних объектов, смена ACL и владельца — нет; иначе выбрать отдельный родитель или явно доверить этим пользователям через -TrustAuthenticatedUsers.
Existing Tracker is owned by TargetUser; TargetUser can delete or alter ACL; Untrusted Tracker boundary owner; Untrusted account can alter Tracker boundary	Исправить права или выбрать другой корень с администраторским/сервисным владельцем. Bootstrap владельца существующего корня не меняет.
Protected Tracker area is absent; ACL still inherits permissions; Protected Tracker owner must be; untrusted account can write protected	Запустить подготовку корня или восстановить защищённый ACL .protected под администратором; затем повторить bootstrap.
Protected ... not a plain file; untrusted owner; permits untrusted write; reparse point	Убрать подменённый файл/ссылку, восстановить обычный файл и доверенного владельца/ACL; повторить bootstrap из чистого клона.
Cannot resolve installed service account; Installed service account SID differs; Service account SID differs; Service account must differ from TargetUser; must not be an administrator	Сверить фактическую учётную запись службы и service.json; использовать отдельную неадминистративную сервисную учётную запись.
ServiceAccountName must be ... at most 20 characters	Передать допустимое имя локальной учётной записи длиной не более 20 символов.
TargetUser env/profile differs from bootstrap JSON; TargetUser settings differ; Existing service is bound to another Tracker root	Вернуть согласованные пути и пользователя либо повторить bootstrap; не переключать службу на другой корень вручную.
ConfigPath must be absolute; Administrative bootstrap JSON v3 is required; Bootstrap JSON must identify the published ... Git source; Protected bootstrap identity is invalid; JSON has an unsupported schema; protected paths differ; service fields are inconsistent; Rebuild must use ... JSON	Использовать абсолютный путь к созданному bootstrap JSON v3; не править JSON вручную, повторить bootstrap из чистого commit. URL marketplace в JSON сверяется, наличие опубликованных плагинов проверяет целевой пользователь отдельно.
Versioned rebuild script must be a plain file; Versioned Install-TaskTrackerV3.ps1 is not yet present	Восстановить версионируемые скрипты в чистом клоне и повторить bootstrap.
Existing service binding differs; Existing service.json is missing; Installed file must be plain	Сверить путь EXE, конфигурацию и сервисную учётную запись; восстановить повреждённую установку до повторного запуска.
Python version setting must be a plain file; Invalid Python version setting; Requirements must be a plain file	Восстановить версионируемые .venv/python_version.txt и requirements.txt как обычные файлы; версия имеет вид python3.11.
Python launcher ...; Python 3.11 is unavailable; could not be selected; Python 3.11 is required	Установить требуемую версию Python и Windows launcher py.exe либо изменить версионируемую настройку; автоматического скачивания и fallback нет.
RuntimeRoot must be an empty plain directory; could not create the protected virtual environment; Virtual environment Python is missing	Проверить права на защищённый staging, поддержку venv у выбранного Python и свободное место; убрать повреждённый staging штатной очисткой.
pip could not install dependencies; Python/PyYAML import failed; Staged Python worker import failed	Обеспечить доступный pip источник пакетов и совместимый PyYAML, затем повторить установку; проверить исходную ошибку импорта.
C# compiler is missing; Staged ServiceHost compilation failed; Stable service EXE copy hash mismatch	При первой сборке или изменении C# проверить компонент .NET Framework 4 и компилятор; при повторном использовании EXE проверить целостность установленного файла.
duplicate TRACKER_MCP_TOKEN; TargetUser env.txt has no TRACKER_MCP_TOKEN; MCP token copies disagree or one is missing; MCP token is empty; MCP token verification failed	Остановить переустановку и согласовать две копии токена: в .protected\mcp-token и пользовательском env.txt; не выводить токен в журнал.
Cannot rotate an absent MCP token; Installed Python MCP service configuration is required for token rotation; MCP service must be Running before token rotation; MCP endpoint did not accept the token	Сначала завершить первичную установку и запустить службу; при ротации проверить конфигурацию, порт и состояние MCP, затем повторить отдельную команду ротации.
Service did not reach Running/Automatic; Installed MCP did not accept the configured token	Проверить журнал службы, её учётную запись, порт и обе копии токена; установщик попытается вернуть прежнюю версию.
Installation failed; previous service restored; MCP token update rolled back	Исправить исходную причину после двоеточия и повторить; прежнее состояние восстановлено.
RECOVERY_INCOMPLETE; SCM failed to delete; newly created service is still registered; Refusing to remove a path outside protected Tracker	Не запускать повторную установку вслепую. Сохранить каталог .rollback-*, проверить пути, службу, токен, ACL и учётную запись вручную под администратором.
Unexpected Tracker root files remain	Установщик возвращает прежнюю службу; проверить перечисленные файлы в корне. Он удаляет только известные старые файлы, неизвестные данные сохраняет.