taskchef 4.1.2 → 5.0.0

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "4.1.2",
+  "version": "5.0.0",
   "description": "Dispatch work from a data-only workspace to visible Codex project tasks.",
   "author": {
     "name": "Favo Yang",

package/README.md

@@ -11,8 +11,8 @@ next request or open any executor and work with it directly.
 
 ## The mental model
 
-- The **dispatcher workspace** is a small folder that stores project routes and
-  task history. A Codex task opened in this folder is the
+- The **dispatcher workspace** is the per-user `~/.agents/taskchef` folder that
+  stores project routes and task history. A Codex task opened in this folder is the
   **dispatcher**.
 - A **configured project** is a local repository or folder where TaskChef may
   send work.
@@ -46,23 +46,16 @@ codex plugin marketplace add favoyang/codex-plugins
 codex plugin add taskchef@favoyang-plugins
 ```
 
-### 2. Create the dispatcher workspace
+### 2. Bootstrap the dispatcher workspace
 
-Create a folder wherever you keep local projects:
-
-```sh
-mkdir -p ~/taskchef
-cd ~/taskchef
-```
-
-Add `~/taskchef` as a project in Codex. Start a new task in that project and
-run the bootstrap skill:
+Invoke the bootstrap skill from any Codex project:
 
 ```text
-$taskchef-bootstrap Set up TaskChef in this folder.
+$taskchef-bootstrap Set up TaskChef.
 ```
 
-Bootstrap creates:
+Bootstrap creates `~/.agents/taskchef`, opens it in the current Codex desktop
+app when it is not already a saved local project, and creates:
 
 ```text
 AGENTS.md
@@ -81,8 +74,9 @@ any of them route to the workspace. If a project needs more context, extend its
 optional `description` field with responsibilities and keywords that
 distinguish it from nearby projects.
 
-The generated `AGENTS.md` turns ordinary requests in this project into
-delegated work. You do not need to name the delegate skill each time.
+The generated `AGENTS.md` turns ordinary requests in the TaskChef project into
+delegated work. From any other project, explicitly invoke `$taskchef-delegate`;
+it uses the same configuration and task history.
 
 ### 3. Delegate the first task
 
@@ -220,6 +214,7 @@ that create and inspect executor tasks. From a source checkout, use
 ```text
 taskchef help
 taskchef doctor
+taskchef workspace path
 taskchef workspace init
 taskchef project add <path>
 taskchef project import [<file> | -]
@@ -232,45 +227,77 @@ taskchef task list
 taskchef task summary
 ```
 
-Workspace and data commands accept `--workspace <path>` and default to the
-current directory. Data commands accept `--json` for machine-readable output.
-Run `taskchef help` for every option.
+Workspace resolution is deterministic: `--workspace <path>`, then the
+`TASKCHEF_WORKSPACE` environment variable, then `~/.agents/taskchef`. The
+current directory is never an implicit workspace. Data commands accept
+`--json` for machine-readable output. Run `taskchef help` for every option.
+
+### One-time upgrade from an older workspace
+
+TaskChef 5 does not include a general migration command. For a one-time upgrade,
+stop delegating and validate the old workspace. Then perform this one-time copy
+only when the destination does not already exist:
+
+```sh
+set -eu
+old_workspace=/path/to/old-taskchef-workspace
+new_workspace="$HOME/.agents/taskchef"
+backup_workspace="$old_workspace.pre-taskchef-5-backup"
+if [ -e "$new_workspace" ]; then
+  printf '%s\n' "Refusing to overwrite existing destination: $new_workspace" >&2
+  exit 1
+fi
+if [ -e "$backup_workspace" ]; then
+  printf '%s\n' "Refusing to overwrite existing backup: $backup_workspace" >&2
+  exit 1
+fi
+taskchef doctor --workspace "$old_workspace"
+cp -pR "$old_workspace" "$backup_workspace"
+install -d -m 700 "$new_workspace"
+install -m 600 "$old_workspace/AGENTS.md" "$new_workspace/AGENTS.md"
+install -m 600 "$old_workspace/taskchef.json" "$new_workspace/taskchef.json"
+install -m 600 "$old_workspace/tasks.jsonl" "$new_workspace/tasks.jsonl"
+taskchef workspace init --workspace "$new_workspace" --register-codex
+taskchef doctor --workspace "$new_workspace"
+```
+
+Keep the backup and old saved Codex project until `project list`, `task list`,
+and `doctor` confirm the expected project and task counts. Do not merge several
+histories by hand; conflicting task or thread IDs require case-by-case review.
 
 ### Project administration
 
 ```sh
-taskchef workspace init --workspace <workspace>
-taskchef doctor --workspace <workspace>
+taskchef workspace init
+taskchef doctor
 
 taskchef project add /workspace/payments \
   --name payments \
   --description "Owns payment authorization, capture, and refunds." \
   --github-repo https://github.com/example/payments-api \
-  --github-repo https://github.com/example/payments-sdk \
-  --workspace <workspace>
+  --github-repo https://github.com/example/payments-sdk
 
-taskchef project list --workspace <workspace>
-taskchef project remove payments --workspace <workspace>
+taskchef project list
+taskchef project remove payments
 ```
 
-Human-readable project listings show one parent row per project. The first
-configured GitHub repository appears on that row; additional repositories
-appear beneath it as indented tree rows, aligned with the repository column and
-with repeated kind and path cells left blank. A project without a configured
-repository has only its parent row, containing `-` in the repository column:
+Human-readable project listings show one row per configured GitHub repository.
+Project details repeat on each row so multi-repository projects remain clear.
+A project without a configured repository has one row containing `-` in the
+repository column:
 
 ```text
 NAME      KIND    GITHUB REPOSITORY                        PATH
 notes     folder  -                                        /workspace/notes
 payments  git     https://github.com/example/payments-api  /workspace/payments
-  └─              https://github.com/example/payments-sdk
+payments  git     https://github.com/example/payments-sdk  /workspace/payments
 ```
 
 Import projects as a JSON array from a file or standard input:
 
 ```sh
-taskchef project import projects.json --workspace <workspace>
-taskchef project import - --workspace <workspace> < projects.json
+taskchef project import projects.json
+taskchef project import - < projects.json
 ```
 
 Import merges by canonical path, preserves an existing name or description
@@ -290,7 +317,7 @@ task lines remain readable without an eager rewrite of the append-only history.
 
 ```sh
 printf '%s\n' '{"id":"c0f010ff-84f2-4838-a69d-0ff1f5d721d7","project":"/workspace/payments","title":"Add retry logs","instruction":"# taskchef_id=c0f010ff-84f2-4838-a69d-0ff1f5d721d7\n\nAdd structured logs for failed retries and test them.","threadId":"019f..."}' |
-  taskchef task record --json --workspace <workspace>
+  taskchef task record --json
 ```
 
 If a task has `threadId: null`, Codex can later find its exact marker and pass
@@ -299,18 +326,17 @@ one-way transition from null to one unique thread ID:
 
 ```sh
 taskchef task resolve c0f010ff-84f2-4838-a69d-0ff1f5d721d7 \
-  --thread-id 019f9d46-f42c-7482-9707-3c107bf241ee \
-  --workspace <workspace>
+  --thread-id 019f9d46-f42c-7482-9707-3c107bf241ee
 ```
 
 Inspect the task history without querying Codex tasks:
 
 ```sh
-taskchef task show t1 --workspace <workspace>
-taskchef task list --workspace <workspace>
-taskchef task list --project payments --workspace <workspace>
-taskchef task list --ascending --workspace <workspace>
-taskchef task summary --workspace <workspace>
+taskchef task show t1
+taskchef task list
+taskchef task list --project payments
+taskchef task list --ascending
+taskchef task summary
 ```
 
 Human-readable task listings put the scannable fields first and the durable ID

package/SPEC.md

@@ -12,7 +12,8 @@ not maintain a second lifecycle database.
 
 ## Core behavior
 
-1. The user submits a request in the dispatcher workspace.
+1. The user submits a request in the dispatcher workspace or explicitly invokes
+   the delegation skill from another Codex project.
 2. TaskChef separates only outcomes that can proceed independently.
 3. It selects each target using configured project metadata and validates the
    selected local path.
@@ -29,7 +30,7 @@ Several active executors may target the same project.
 ## Workspace layout
 
 ```text
-taskchef/
+~/.agents/taskchef/
 ├── AGENTS.md
 ├── taskchef.json
 └── tasks.jsonl
@@ -44,10 +45,27 @@ instructions and refreshes only the managed block.
 log when missing, refreshes managed instructions, and removes legacy TaskChef
 skill symlinks.
 
+Every command resolves one workspace in this precedence order:
+
+1. explicit `--workspace <path>`
+2. `TASKCHEF_WORKSPACE`
+3. `~/.agents/taskchef`
+
+The current directory is never an implicit workspace. `workspace path` exposes
+the resolved absolute path and its source. Bootstrap compares this canonical
+path with native Codex projects, and when absent invokes the validated
+`codex app <path>` command before verifying the native list again. It never
+uses `codex add` or a hard-coded application bundle path.
+
 `doctor` validates configuration, project paths, the JSONL log, managed
 instructions, and the absence of legacy TaskChef skill links without modifying
 the workspace.
 
+Neither the workspace nor any directory containing it can be configured as a
+delegation project. All project configuration and task-history mutations share
+one cross-process workspace lock. Writers reread and validate state while
+holding that lock and publish complete files by atomic replacement.
+
 ## Project configuration
 
 `taskchef.json` is the user-facing routing configuration:

package/assets/taskchef-dispatcher-instructions.md

@@ -1,7 +1,7 @@
 <!-- taskchef:dispatcher-instructions:start -->
 # TaskChef Dispatcher Instructions
 
-This repository is a TaskChef dispatcher workspace.
+This folder is the canonical per-user TaskChef dispatcher workspace.
 
 - Use `$taskchef-bootstrap` when initializing or refreshing this workspace,
   changing or listing its configured projects, running TaskChef doctor,
@@ -18,4 +18,6 @@ This repository is a TaskChef dispatcher workspace.
 - Use `$taskchef-report` only when the user asks for a live report about
   delegated work. Reports query the recorded Codex tasks once and do not
   write status or results to this workspace.
+- Explicit invocations of TaskChef skills from other Codex projects use this
+  same workspace and task history through TaskChef's global resolution rules.
 <!-- taskchef:dispatcher-instructions:end -->

package/index.js

@@ -42,3 +42,14 @@ export {
   structuredDelegatedInputs,
   taskChefMarker,
 } from "./src/delegation.js";
+
+export {
+  TASKCHEF_WORKSPACE_ENV,
+  defaultWorkspacePath,
+  resolveWorkspacePath,
+} from "./src/workspace-path.js";
+
+export {
+  discoverCodexCli,
+  openWorkspaceInCodex,
+} from "./src/codex-app.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "4.1.2",
+  "version": "5.0.0",
   "description": "A non-blocking interactive dispatcher for visible Codex tasks.",
   "license": "MIT",
   "author": "Favo Yang",

package/skills/taskchef-bootstrap/SKILL.md

@@ -5,7 +5,8 @@ description: "Initialize, diagnose, or refresh TaskChef dispatcher workspaces, p
 
 # TaskChef Bootstrap
 
-Initialize or refresh a data-only TaskChef dispatcher workspace.
+Initialize or refresh the per-user TaskChef dispatcher workspace at
+`~/.agents/taskchef`.
 
 Resolve this skill directory with `realpath`. The TaskChef plugin root is two
 parents above the skill directory. Invoke `<plugin-root>/bin/taskchef.js` for
@@ -22,21 +23,37 @@ all deterministic workspace operations.
 
 ## Initialize and repair
 
-1. Run `workspace init --json`. It takes no stdin, creates an empty
+1. Run `workspace path --json` and use its returned canonical path for native
+   project comparisons. The CLI resolves `--workspace`, then
+   `TASKCHEF_WORKSPACE`, then `~/.agents/taskchef`; do not infer a workspace
+   from the current project.
+2. List native Codex projects once. If an exact canonical-path local project
+   already exists, run `workspace init --json`. Otherwise run
+   `workspace init --register-codex --json`, then list native projects once more
+   and require one exact canonical-path local project. `--register-codex`
+   invokes the supported `codex app <path>` command through a validated Codex
+   CLI discovered from the current desktop environment; never invoke
+   `codex add` or hard-code an application bundle path.
+3. `workspace init` takes no stdin, creates an empty
    configuration when missing, creates the append-only task log, refreshes
    managed instructions, and removes legacy TaskChef skill links. The installed
    plugin provides all three TaskChef skills outside the dispatcher workspace.
-2. Run `doctor --json` after setup or when the user asks to diagnose the
+4. Run `doctor --json` after setup or when the user asks to diagnose the
    workspace. Doctor is read-only. Rerun `workspace init --json` to repair the
    managed scaffold.
-3. Report the actions or failed checks. End without dispatching unless the user
+5. Report the actions or failed checks. A successful initialization with failed
+   Codex opening remains initialized but not verified as a saved local project.
+   End without dispatching unless the user
    separately requested work.
 
 ## Configure projects
 
-1. List native Codex projects once when discovery is necessary. Configure only
+1. Reuse the native Codex project list from initialization when available.
+   Configure only
    projects local to the TaskChef workspace's execution host. Remote connection
    projects are outside the v1 contract.
+   Never configure the TaskChef dispatcher workspace or a directory containing
+   it as a routing target.
 2. Add one project with `project add <path>`, normally supplying `--name` and a
    curated `--description`. The CLI detects Git status, exact Git root, and a
    canonical GitHub `origin`. Repeat `--github-repo <url>` to advertise several

package/skills/taskchef-bootstrap/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "TaskChef Bootstrap"
-  short_description: "Bootstrap TaskChef dispatcher workspaces"
-  default_prompt: "Use $taskchef-bootstrap to initialize or refresh this TaskChef dispatcher workspace."
+  short_description: "Bootstrap the per-user TaskChef workspace"
+  default_prompt: "Use $taskchef-bootstrap to initialize or refresh my per-user TaskChef dispatcher workspace."

package/skills/taskchef-delegate/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: taskchef-delegate
-description: "Dispatch actionable requests from an initialized TaskChef workspace into independently openable Codex project tasks. Use for ordinary work requests in a TaskChef workspace, explicit delegation, or splitting independent work across projects. Preserve unresolved delegations for later marker-based recovery, and never use subagents, hooks, schedules, daemons, or executor-completion waiting."
+description: "Dispatch actionable requests through the per-user TaskChef workspace into independently openable Codex project tasks. Use for ordinary work requests in the TaskChef project, explicit delegation from any project, or splitting independent work across projects. Preserve unresolved delegations for later marker-based recovery, and never use subagents, hooks, schedules, daemons, or executor-completion waiting."
 ---
 
 # TaskChef Delegate
 
-Create real Codex tasks from a TaskChef data workspace and return immediately.
+Create real Codex tasks through the canonical per-user TaskChef data workspace
+and return immediately.
 
 Resolve this skill directory with `realpath`. The TaskChef plugin root is two
 parents above the skill directory. Use the TaskChef executable under that root
@@ -26,10 +27,13 @@ for all deterministic workspace and task-record operations.
 
 ## Dispatch
 
-1. Run
-   `<plugin-root>/bin/taskchef.js project list --json --workspace <workspace>`
+1. Run `<plugin-root>/bin/taskchef.js workspace path --json`, then run
+   `<plugin-root>/bin/taskchef.js project list --json`
    to load and validate the configured routing targets. Use
    `$taskchef-bootstrap` if the workspace is missing or unhealthy.
+   The CLI resolves `--workspace`, then `TASKCHEF_WORKSPACE`, then
+   `~/.agents/taskchef`; do not substitute the current project. Reject the
+   dispatcher workspace itself as a target.
 2. Split the request into the smallest independently useful outcomes. Include
    constraints, expected testing, and reporting in every instruction.
 3. Classify against configured `name`, every URL in the `githubRepos` list, and
@@ -50,7 +54,7 @@ for all deterministic workspace and task-record operations.
 6. Create one real Codex task using the exact configured project, a local
    environment on its executor host, the marked instruction, and a short title.
 7. When `create_thread` returns a durable `threadId`, immediately run
-   `<plugin-root>/bin/taskchef.js task record --json --workspace <workspace>`.
+   `<plugin-root>/bin/taskchef.js task record --json`.
    Send exactly `id`, `project`, `title`, `instruction`, and `threadId` as JSON
    on stdin. Use the configured project path for `project`, and send the marked
    instruction unchanged. Never persist a provisional `clientThreadId` or
@@ -114,6 +118,6 @@ Codex and use the CLI only for validated workspace data operations.
 
 When a later Codex workflow finds exactly one durable thread whose structured
 delegated input contains an unresolved task's exact marker, run
-`<plugin-root>/bin/taskchef.js task resolve <task-id> --thread-id <thread-id> --json --workspace <workspace>`.
+`<plugin-root>/bin/taskchef.js task resolve <task-id> --thread-id <thread-id> --json`.
 Never edit `tasks.jsonl` directly. The CLI permits only an idempotent one-way
 transition from `threadId: null` to one unique durable thread ID.

package/skills/taskchef-report/SKILL.md

@@ -5,8 +5,8 @@ description: "Report the live state of Codex tasks recorded in a TaskChef task h
 
 # TaskChef Report
 
-Read the TaskChef task history and report the current state of its Codex
-tasks once.
+Read the canonical per-user TaskChef task history and report the current state
+of its Codex tasks once.
 
 Resolve this skill directory with `realpath`. The TaskChef plugin root is two
 parents above the skill directory. Invoke `<plugin-root>/bin/taskchef.js` for
@@ -14,13 +14,16 @@ all deterministic task-log operations.
 
 ## Report
 
-1. Select only the tasks the user asked about:
+1. Run `<plugin-root>/bin/taskchef.js workspace path --json`. The CLI resolves
+   `--workspace`, then `TASKCHEF_WORKSPACE`, then `~/.agents/taskchef`; never
+   infer the history from the current project. Select only the tasks the user
+   asked about:
    - For an exact task ID, run
-     `<plugin-root>/bin/taskchef.js task show <task-id> --json --workspace <workspace>`.
+     `<plugin-root>/bin/taskchef.js task show <task-id> --json`.
    - For a project, run
-     `<plugin-root>/bin/taskchef.js task list --project <name-or-path> --json --workspace <workspace>`.
+     `<plugin-root>/bin/taskchef.js task list --project <name-or-path> --json`.
    - For a title or other description, run
-     `<plugin-root>/bin/taskchef.js task list --json --workspace <workspace>`
+     `<plugin-root>/bin/taskchef.js task list --json`
      once, then select matching entries. Ask the user if the match is ambiguous.
    - Use the full list only when the user asks for an overview of the task history.
 2. Separate entries whose `threadId` is `null`. For those entries, take one
@@ -28,7 +31,7 @@ all deterministic task-log operations.
    and inspect candidate structured delegated inputs. Use title only to
    prioritize candidates, never to exclude them. When exactly one candidate
    starts with the task's exact marker, run
-   `<plugin-root>/bin/taskchef.js task resolve <task-id> --thread-id <thread-id> --json --workspace <workspace>`.
+   `<plugin-root>/bin/taskchef.js task resolve <task-id> --thread-id <thread-id> --json`.
    Do not resolve zero or multiple matches. Report unmatched entries as
    recorded but unresolved and do not pass them to native thread tools.
 3. Query every resolved or previously durable thread exactly once using

package/src/cli.js

@@ -1,6 +1,9 @@
-import { readFile } from "node:fs/promises";
+import { access, readFile, realpath } from "node:fs/promises";
 import path from "node:path";
 
+import { openWorkspaceInCodex } from "./codex-app.js";
+import { resolveWorkspacePath } from "./workspace-path.js";
+
 import {
   addProject,
   buildTaskSummary,
@@ -15,8 +18,6 @@ import {
   resolveTask,
 } from "./workspace.js";
 
-const BLANK_TABLE_CELL = Symbol("blank table cell");
-
 async function readStdin() {
   let input = "";
   process.stdin.setEncoding("utf8");
@@ -77,8 +78,14 @@ function validateCommandArgs(
   }
 }
 
+function workspaceSelection(args) {
+  return resolveWorkspacePath({
+    explicit: args.includes("--workspace") ? option(args, "--workspace") : null,
+  });
+}
+
 function workspaceRoot(args) {
-  return path.resolve(option(args, "--workspace", process.cwd()));
+  return workspaceSelection(args).workspace;
 }
 
 function print(value, args, human) {
@@ -90,11 +97,9 @@ function print(value, args, human) {
 }
 
 function table(headers, rows) {
-  const display = (value) => {
-    if (value === BLANK_TABLE_CELL) return "";
-    if (value === null || value === undefined || value === "") return "-";
-    return String(value);
-  };
+  const display = (value) => value === null || value === undefined || value === ""
+    ? "-"
+    : String(value);
   const widths = headers.map((header, index) =>
     Math.max(header.length, ...rows.map((row) => display(row[index]).length)));
   const format = (row) => row.map((value, index) => index === row.length - 1
@@ -105,18 +110,13 @@ function table(headers, rows) {
 
 function projectRows(projects) {
   return projects.flatMap((project) => {
-    const [primaryRepository = null, ...additionalRepositories] = project.githubRepos;
-    return [[
+    const repositories = project.githubRepos.length > 0 ? project.githubRepos : [null];
+    return repositories.map((repository) => [
       project.name,
       project.isGitRepository ? "git" : "folder",
-      primaryRepository,
-      project.path,
-    ], ...additionalRepositories.map((repository, index) => [
-      `  ${index === additionalRepositories.length - 1 ? "└─" : "├─"}`,
-      BLANK_TABLE_CELL,
       repository,
-      BLANK_TABLE_CELL,
-    ])];
+      project.path,
+    ]);
   });
 }
 
@@ -136,15 +136,46 @@ function sortTasksByCreatedAt(tasks, ascending) {
 }
 
 async function initialize(args) {
-  validateCommandArgs(args, 2, { values: ["--workspace"], switches: ["--json"] });
-  const result = await initializeWorkspace(workspaceRoot(args));
+  validateCommandArgs(args, 2, {
+    values: ["--workspace", "--codex-cli"],
+    switches: ["--json", "--register-codex"],
+  });
+  const resolution = workspaceSelection(args);
+  const result = await initializeWorkspace(resolution.workspace);
+  result.resolutionSource = resolution.source;
+  let registrationFailed = false;
+  if (args.includes("--register-codex")) {
+    try {
+      result.registration = await openWorkspaceInCodex(result.workspace, {
+        explicit: args.includes("--codex-cli") ? option(args, "--codex-cli") : null,
+      });
+    } catch (error) {
+      registrationFailed = true;
+      result.registration = { status: "failed", reason: error.message };
+    }
+  }
   print(result, args, (value) => [
     `Workspace: ${value.workspace}`,
     `Configuration: ${value.config.action}`,
     `Task log: ${value.tasks.action}`,
     `Instructions: ${value.instructions.action}`,
     `Legacy skill links removed: ${value.legacySkills.removed.length}`,
+    ...(value.registration ? [`Codex opening: ${value.registration.status}`] : []),
   ].join("\n"));
+  return registrationFailed ? 5 : 0;
+}
+
+async function workspacePath(args) {
+  validateCommandArgs(args, 2, { values: ["--workspace"], switches: ["--json"] });
+  const resolution = workspaceSelection(args);
+  const exists = await access(resolution.workspace).then(() => true).catch(() => false);
+  const workspace = exists ? await realpath(resolution.workspace) : resolution.workspace;
+  print({
+    schemaVersion: 1,
+    workspace,
+    source: resolution.source,
+    exists,
+  }, args, (value) => value.workspace);
   return 0;
 }
 
@@ -286,7 +317,8 @@ function usage() {
 Usage:
   taskchef help
   taskchef doctor [--json] [--workspace <path>]
-  taskchef workspace init [--json] [--workspace <path>]
+  taskchef workspace path [--json] [--workspace <path>]
+  taskchef workspace init [--register-codex] [--codex-cli <path>] [--json] [--workspace <path>]
   taskchef project add <path> [--name <name>] [--description <text>] [--github-repo <url> ... | --no-github] [--json] [--workspace <path>]
   taskchef project import [<file> | -] [--replace] [--json] [--workspace <path>]
   taskchef project list [--json] [--workspace <path>]
@@ -299,6 +331,8 @@ Usage:
 
 Task record reads JSON from standard input. Project import reads a JSON
 array from a file, or from standard input when the source is '-' or omitted.
+Workspace resolution precedence is --workspace, TASKCHEF_WORKSPACE, then
+~/.agents/taskchef.
 `);
 }
 
@@ -308,6 +342,7 @@ export async function runCli(args) {
     return 0;
   }
   if (args[0] === "doctor") return doctor(args);
+  if (args[0] === "workspace" && args[1] === "path") return workspacePath(args);
   if (args[0] === "workspace" && args[1] === "init") return initialize(args);
   if (args[0] === "project" && args[1] === "add") return projectAdd(args);
   if (args[0] === "project" && args[1] === "import") return projectImport(args);

package/src/codex-app.js

@@ -0,0 +1,77 @@
+import { execFile as execFileCallback } from "node:child_process";
+import { access } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+
+const execFile = promisify(execFileCallback);
+const CODEX_COMMAND_TIMEOUT_MS = 10_000;
+
+function runCodex(run, filePath, args) {
+  return run(filePath, args, { timeout: CODEX_COMMAND_TIMEOUT_MS, killSignal: "SIGKILL" });
+}
+
+async function executable(filePath) {
+  try {
+    await access(filePath, 1);
+    return path.resolve(filePath);
+  } catch {
+    return null;
+  }
+}
+
+function pathCandidates(env) {
+  return (env.PATH ?? "")
+    .split(path.delimiter)
+    .filter(Boolean)
+    .map((directory) => path.join(directory, process.platform === "win32" ? "codex.exe" : "codex"));
+}
+
+async function supportsAppCommand(filePath, run) {
+  try {
+    const { stdout, stderr } = await runCodex(run, filePath, ["app", "--help"]);
+    return /(?:^|\n)Usage:\s+codex\s+app(?:\s|$)/.test(`${stdout}\n${stderr}`);
+  } catch {
+    return false;
+  }
+}
+
+export async function discoverCodexCli({
+  explicit = null,
+  env = process.env,
+  run = execFile,
+} = {}) {
+  const override = explicit ?? env.TASKCHEF_CODEX_CLI ?? null;
+  if (override !== null) {
+    const candidate = await executable(path.resolve(override));
+    if (!candidate) throw new Error(`Codex CLI is not executable: ${override}`);
+    if (!(await supportsAppCommand(candidate, run))) {
+      throw new Error(`Codex CLI does not support the app command: ${candidate}`);
+    }
+    return { path: candidate, source: explicit !== null ? "explicit" : "environment" };
+  }
+
+  let candidate = null;
+  for (const pathCandidate of pathCandidates(env)) {
+    candidate = await executable(pathCandidate);
+    if (candidate) break;
+  }
+  if (!candidate) throw new Error("Codex CLI was not found in PATH; pass --codex-cli");
+  if (!(await supportsAppCommand(candidate, run))) {
+    throw new Error(`Codex CLI does not support the app command: ${candidate}`);
+  }
+  const bundled = candidate.includes(`${path.sep}Contents${path.sep}Resources${path.sep}`);
+  return { path: candidate, source: bundled ? "desktop-path" : "path" };
+}
+
+export async function openWorkspaceInCodex(workspace, options = {}) {
+  const run = options.run ?? execFile;
+  const cli = await discoverCodexCli({ ...options, run });
+  await runCodex(run, cli.path, ["app", workspace]);
+  return {
+    status: "requested",
+    mechanism: "codex-app",
+    codexCli: cli.path,
+    codexCliSource: cli.source,
+    workspace,
+  };
+}

package/src/workspace-path.js

@@ -0,0 +1,44 @@
+import os from "node:os";
+import path from "node:path";
+
+export const TASKCHEF_WORKSPACE_ENV = "TASKCHEF_WORKSPACE";
+
+export function defaultWorkspacePath({ homedir = os.homedir() } = {}) {
+  return path.join(homedir, ".agents", "taskchef");
+}
+
+function expandHome(value, homedir) {
+  if (value === "~") return homedir;
+  if (value.startsWith("~/") || value.startsWith("~\\")) {
+    return path.join(homedir, value.slice(2));
+  }
+  return value;
+}
+
+export function resolveWorkspacePath({
+  explicit = null,
+  env = process.env,
+  homedir = os.homedir(),
+  cwd = process.cwd(),
+} = {}) {
+  let source = "default";
+  let value = defaultWorkspacePath({ homedir });
+  if (env[TASKCHEF_WORKSPACE_ENV] !== undefined) {
+    if (typeof env[TASKCHEF_WORKSPACE_ENV] !== "string" || env[TASKCHEF_WORKSPACE_ENV].trim() === "") {
+      throw new Error(`${TASKCHEF_WORKSPACE_ENV} must be a non-empty path`);
+    }
+    source = "environment";
+    value = env[TASKCHEF_WORKSPACE_ENV];
+  }
+  if (explicit !== null) {
+    if (typeof explicit !== "string" || explicit.trim() === "") {
+      throw new Error("--workspace must be a non-empty path");
+    }
+    source = "explicit";
+    value = explicit;
+  }
+  return {
+    workspace: path.resolve(cwd, expandHome(value, homedir)),
+    source,
+  };
+}

package/src/workspace.js

@@ -1,6 +1,7 @@
 import { execFile as execFileCallback } from "node:child_process";
 import {
   access,
+  chmod,
   lstat,
   mkdir,
   readFile,
@@ -39,7 +40,7 @@ const TASKCHEF_SKILL_NAMES = [
 const LEGACY_TASKCHEF_SKILL_NAMES = [...TASKCHEF_SKILL_NAMES, "taskchef-reconcile"];
 const SKILLS_SOURCE_ROOT = fileURLToPath(new URL("../skills/", import.meta.url));
 const DISPATCH_FILE_NAME = "tasks.jsonl";
-const DISPATCH_LOCK_NAME = ".taskchef-dispatch.lock";
+const WORKSPACE_LOCK_NAME = ".taskchef-workspace.lock";
 const SAFE_ID = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
 const CURRENT_SCHEMA_VERSION = 2;
 const LEGACY_SCHEMA_VERSION = 1;
@@ -147,14 +148,22 @@ async function managedRegularFileExists(filePath) {
   return true;
 }
 
-async function withDispatchLock(workspaceRoot, operation) {
-  const dispatchPath = path.join(workspaceRoot, DISPATCH_FILE_NAME);
-  const lockPath = path.join(workspaceRoot, DISPATCH_LOCK_NAME);
-  const release = await lockfile.lock(dispatchPath, {
+function assertWorkspaceOutsideProject(workspaceRoot, projectPath) {
+  const relative = path.relative(projectPath, workspaceRoot);
+  if (relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative))) {
+    throw new Error(
+      "TaskChef workspace cannot be configured as its own delegation project or inside a delegation project",
+    );
+  }
+}
+
+async function withWorkspaceLock(workspaceRoot, operation) {
+  const lockPath = path.join(workspaceRoot, WORKSPACE_LOCK_NAME);
+  const release = await lockfile.lock(workspaceRoot, {
     realpath: false,
     lockfilePath: lockPath,
-    stale: 5_000,
-    update: 1_000,
+    stale: 600_000,
+    update: 10_000,
     retries: { retries: 70, factor: 1, minTimeout: 100, maxTimeout: 100 },
   });
   try {
@@ -211,7 +220,7 @@ async function writeTextAtomic(filePath, value) {
   const mode = await stat(filePath)
     .then((details) => details.mode & 0o777)
     .catch((error) => {
-      if (error.code === "ENOENT") return 0o644;
+      if (error.code === "ENOENT") return 0o600;
       throw error;
     });
   await writeFile(temporaryPath, value, {
@@ -551,43 +560,55 @@ async function ensureDispatchFile(workspaceRoot) {
 
 export async function initializeWorkspace(workspaceRoot) {
   const requestedRoot = path.resolve(workspaceRoot);
-  await mkdir(requestedRoot, { recursive: true });
+  await mkdir(requestedRoot, { recursive: true, mode: 0o700 });
+  const requestedDetails = await lstat(requestedRoot);
+  if (requestedDetails.isSymbolicLink() || !requestedDetails.isDirectory()) {
+    throw new Error(`workspace path is not a real directory: ${requestedRoot}`);
+  }
+  if (typeof process.getuid === "function" && requestedDetails.uid !== process.getuid()) {
+    throw new Error(`workspace is not owned by the current user: ${requestedRoot}`);
+  }
   const root = await realpath(requestedRoot);
-  const configPath = path.join(root, "taskchef.json");
-  const configExists = await managedRegularFileExists(configPath);
-  const storedConfigVersion = configExists
-    ? JSON.parse(await readFile(configPath, "utf8")).schemaVersion
-    : null;
-  const config = configExists
-    ? await readConfig(root, { checkPaths: false })
-    : { schemaVersion: CURRENT_SCHEMA_VERSION, projects: [] };
-  const dispatchPath = path.join(root, DISPATCH_FILE_NAME);
-  if (configExists && (await managedRegularFileExists(dispatchPath))) {
-    await readDispatchesUnlocked(root);
-  }
-  const { legacySkills } = await ensureWorkspaceSkills(root);
-  if (!configExists) await writeJsonAtomic(configPath, config, { exclusive: true });
-  else if (storedConfigVersion !== CURRENT_SCHEMA_VERSION) {
-    await writeJsonAtomic(configPath, config);
-  }
-  const tasks = await ensureDispatchFile(root);
-  const instructions = await ensureWorkspaceInstructions(root).catch(async (error) => {
-    if (!configExists) await unlink(configPath).catch(() => {});
-    throw error;
+  await chmod(root, 0o700);
+  return withWorkspaceLock(root, async () => {
+    const configPath = path.join(root, "taskchef.json");
+    const configExists = await managedRegularFileExists(configPath);
+    const storedConfigVersion = configExists
+      ? JSON.parse(await readFile(configPath, "utf8")).schemaVersion
+      : null;
+    const config = configExists
+      ? await readConfig(root, { checkPaths: false })
+      : { schemaVersion: CURRENT_SCHEMA_VERSION, projects: [] };
+    const dispatchPath = path.join(root, DISPATCH_FILE_NAME);
+    if (configExists && (await managedRegularFileExists(dispatchPath))) {
+      await readDispatchesUnlocked(root);
+    }
+    const { legacySkills } = await ensureWorkspaceSkills(root);
+    if (!configExists) await writeJsonAtomic(configPath, config, { exclusive: true });
+    else if (storedConfigVersion !== CURRENT_SCHEMA_VERSION) {
+      await writeJsonAtomic(configPath, config);
+    }
+    const tasks = await ensureDispatchFile(root);
+    const instructions = await ensureWorkspaceInstructions(root).catch(async (error) => {
+      if (!configExists) await unlink(configPath).catch(() => {});
+      throw error;
+    });
+    await Promise.all([configPath, tasks.path, instructions.path]
+      .map((filePath) => chmod(filePath, 0o600)));
+    return {
+      workspace: root,
+      config: {
+        path: configPath,
+        action: !configExists
+          ? "created"
+          : storedConfigVersion === CURRENT_SCHEMA_VERSION ? "unchanged" : "migrated",
+        value: config,
+      },
+      tasks,
+      instructions,
+      legacySkills,
+    };
   });
-  return {
-    workspace: root,
-    config: {
-      path: configPath,
-      action: !configExists
-        ? "created"
-        : storedConfigVersion === CURRENT_SCHEMA_VERSION ? "unchanged" : "migrated",
-      value: config,
-    },
-    tasks,
-    instructions,
-    legacySkills,
-  };
 }
 
 export async function readConfig(workspaceRoot, { checkPaths = true } = {}) {
@@ -596,8 +617,10 @@ export async function readConfig(workspaceRoot, { checkPaths = true } = {}) {
   if (!(await managedRegularFileExists(configPath))) {
     throw new Error(`configuration does not exist: ${configPath}`);
   }
-  const config = JSON.parse(await readFile(configPath, "utf8"));
-  return validateConfig(config, { checkPaths });
+  const config = await validateConfig(JSON.parse(await readFile(configPath, "utf8")), { checkPaths });
+  const canonicalRoot = await realpath(root);
+  for (const project of config.projects) assertWorkspaceOutsideProject(canonicalRoot, project.path);
+  return config;
 }
 
 export async function listProjects(workspaceRoot) {
@@ -606,68 +629,76 @@ export async function listProjects(workspaceRoot) {
 }
 
 export async function addProject(workspaceRoot, input) {
-  const root = path.resolve(workspaceRoot);
-  const config = await readConfig(root);
-  const project = await inspectProject(input);
-  const updated = await validateConfig({
-    schemaVersion: CURRENT_SCHEMA_VERSION,
-    projects: [...config.projects, project],
+  const root = await realpath(path.resolve(workspaceRoot));
+  return withWorkspaceLock(root, async () => {
+    const config = await readConfig(root);
+    const project = await inspectProject(input);
+    assertWorkspaceOutsideProject(root, project.path);
+    const updated = await validateConfig({
+      schemaVersion: CURRENT_SCHEMA_VERSION,
+      projects: [...config.projects, project],
+    });
+    await writeJsonAtomic(path.join(root, "taskchef.json"), updated);
+    return project;
   });
-  await writeJsonAtomic(path.join(root, "taskchef.json"), updated);
-  return project;
 }
 
 export async function importProjects(workspaceRoot, inputs, { replace = false } = {}) {
   if (!Array.isArray(inputs)) throw new Error("project import must be a JSON array");
-  const root = path.resolve(workspaceRoot);
-  const current = await readConfig(root, { checkPaths: !replace });
-  const imported = [];
-  for (const [index, input] of inputs.entries()) {
-    const canonicalPath = await canonicalDirectory(input?.path);
-    const existing = current.projects.find((project) => project.path === canonicalPath);
-    const mergedInput = { ...input, path: canonicalPath };
-    if (!("name" in mergedInput) && existing) mergedInput.name = existing.name;
-    if (!("description" in mergedInput) && existing?.description) {
-      mergedInput.description = existing.description;
+  const root = await realpath(path.resolve(workspaceRoot));
+  return withWorkspaceLock(root, async () => {
+    const current = await readConfig(root, { checkPaths: !replace });
+    const imported = [];
+    for (const [index, input] of inputs.entries()) {
+      const canonicalPath = await canonicalDirectory(input?.path);
+      assertWorkspaceOutsideProject(root, canonicalPath);
+      const existing = current.projects.find((project) => project.path === canonicalPath);
+      const mergedInput = { ...input, path: canonicalPath };
+      if (!("name" in mergedInput) && existing) mergedInput.name = existing.name;
+      if (!("description" in mergedInput) && existing?.description) {
+        mergedInput.description = existing.description;
+      }
+      if (existing && !replace) {
+        const importedRepositories = "githubRepos" in mergedInput
+          ? normalizeGithubRepositories(mergedInput.githubRepos, `projects[${index}].githubRepos`)
+          : [];
+        mergedInput.githubRepos = [...existing.githubRepos, ...importedRepositories];
+      }
+      imported.push(await inspectProject(mergedInput, index));
     }
-    if (existing && !replace) {
-      const importedRepositories = "githubRepos" in mergedInput
-        ? normalizeGithubRepositories(mergedInput.githubRepos, `projects[${index}].githubRepos`)
-        : [];
-      mergedInput.githubRepos = [...existing.githubRepos, ...importedRepositories];
+    const projects = replace ? [] : [...current.projects];
+    for (const project of imported) {
+      const index = projects.findIndex((existing) => existing.path === project.path);
+      if (index === -1) projects.push(project);
+      else projects[index] = project;
     }
-    imported.push(await inspectProject(mergedInput, index));
-  }
-  const projects = replace ? [] : [...current.projects];
-  for (const project of imported) {
-    const index = projects.findIndex((existing) => existing.path === project.path);
-    if (index === -1) projects.push(project);
-    else projects[index] = project;
-  }
-  const config = await validateConfig({ schemaVersion: CURRENT_SCHEMA_VERSION, projects });
-  await writeJsonAtomic(path.join(root, "taskchef.json"), config);
-  return {
-    mode: replace ? "replace" : "merge",
-    importedCount: imported.length,
-    projectCount: config.projects.length,
-    projects: imported,
-  };
+    const config = await validateConfig({ schemaVersion: CURRENT_SCHEMA_VERSION, projects });
+    await writeJsonAtomic(path.join(root, "taskchef.json"), config);
+    return {
+      mode: replace ? "replace" : "merge",
+      importedCount: imported.length,
+      projectCount: config.projects.length,
+      projects: imported,
+    };
+  });
 }
 
 export async function removeProject(workspaceRoot, name) {
-  const root = path.resolve(workspaceRoot);
-  const config = await readConfig(root, { checkPaths: false });
-  const index = config.projects.findIndex(
-    (project) => project.name.toLowerCase() === requireString(name, "project name").toLowerCase(),
-  );
-  if (index === -1) throw new Error(`configured project not found: ${name}`);
-  const [project] = config.projects.slice(index, index + 1);
-  const projects = config.projects.filter((_, projectIndex) => projectIndex !== index);
-  await writeJsonAtomic(path.join(root, "taskchef.json"), {
-    schemaVersion: CURRENT_SCHEMA_VERSION,
-    projects,
+  const root = await realpath(path.resolve(workspaceRoot));
+  return withWorkspaceLock(root, async () => {
+    const config = await readConfig(root, { checkPaths: false });
+    const index = config.projects.findIndex(
+      (project) => project.name.toLowerCase() === requireString(name, "project name").toLowerCase(),
+    );
+    if (index === -1) throw new Error(`configured project not found: ${name}`);
+    const [project] = config.projects.slice(index, index + 1);
+    const projects = config.projects.filter((_, projectIndex) => projectIndex !== index);
+    await writeJsonAtomic(path.join(root, "taskchef.json"), {
+      schemaVersion: CURRENT_SCHEMA_VERSION,
+      projects,
+    });
+    return { project };
   });
-  return { project };
 }
 
 async function validateDispatchShape(dispatch, name = "task") {
@@ -753,20 +784,20 @@ export async function listTasks(workspaceRoot) {
 export async function recordTask(workspaceRoot, input, { now } = {}) {
   requireExactFields(input, RECORD_DISPATCH_FIELDS, "task input");
   const root = await realpath(path.resolve(workspaceRoot));
-  const config = await readConfig(root);
-  const projectPath = await canonicalDirectory(input.project);
-  const project = config.projects.find((candidate) => candidate.path === projectPath);
-  if (!project) throw new Error(`project is not configured in taskchef.json: ${projectPath}`);
-  const dispatch = await validateDispatchShape({
-    schemaVersion: CURRENT_SCHEMA_VERSION,
-    id: input.id,
-    project,
-    title: input.title,
-    instruction: input.instruction,
-    threadId: input.threadId,
-    createdAt: now ?? new Date().toISOString(),
-  });
-  await withDispatchLock(root, async () => {
+  return withWorkspaceLock(root, async () => {
+    const config = await readConfig(root);
+    const projectPath = await canonicalDirectory(input.project);
+    const project = config.projects.find((candidate) => candidate.path === projectPath);
+    if (!project) throw new Error(`project is not configured in taskchef.json: ${projectPath}`);
+    const dispatch = await validateDispatchShape({
+      schemaVersion: CURRENT_SCHEMA_VERSION,
+      id: input.id,
+      project,
+      title: input.title,
+      instruction: input.instruction,
+      threadId: input.threadId,
+      createdAt: now ?? new Date().toISOString(),
+    });
     const existing = await readDispatchesUnlocked(root);
     if (existing.some((item) => item.id === dispatch.id)) {
       throw new Error(`task already exists: ${dispatch.id}`);
@@ -778,15 +809,15 @@ export async function recordTask(workspaceRoot, input, { now } = {}) {
       throw new Error(`threadId is already recorded: ${dispatch.threadId}`);
     }
     await appendDispatchesAtomic(root, [dispatch]);
+    return dispatch;
   });
-  return dispatch;
 }
 
 export async function resolveTask(workspaceRoot, taskId, threadId) {
   const id = requireSafeId(taskId, "taskId");
   const durableThreadId = normalizeDurableThreadId(threadId);
   const root = await realpath(path.resolve(workspaceRoot));
-  return withDispatchLock(root, async () => {
+  return withWorkspaceLock(root, async () => {
     const records = await readDispatchRecordsUnlocked(root);
     const dispatches = records.map((record) => record.normalized);
     const index = dispatches.findIndex((dispatch) => dispatch.id === id);