ctask resume <archived-workspace> printed both the helpful [ctask]
diagnostic + restore hint AND a redundant trailing "Error: workspace
archived" line from Cobra's default error rendering. Cosmetic but
unprofessional.
Add an errArchivedWorkspace sentinel and have runResume flip
SilenceErrors only when the inner error is that sentinel. All other
resume errors (lookup failure, metadata write failure, etc.) continue
to flow through Cobra's default rendering unchanged — we only silence
the case where we have already printed an equivalent diagnostic
ourselves.
Verified end-to-end through Cobra Execute (not just runResume direct
invocation) so the SilenceErrors-flip-from-RunE timing is exercised.
Bring docs/commands.md up to current state. The document was last
substantively updated in v0.5; v0.5.2 (restore/notes/path/list --names/
completion + archived-inclusive lookup), v0.5.3 (attach + --direct +
persistent session mode + doctor tmux check), and v0.5.4 (info Session
block + list SESSION column) were all undocumented.
Format follows the spec section §3: each command has Purpose, Usage,
Scenarios, Examples, Flags, Notes, Related. Sections are kept short
(roughly one screen each) — if a command needed more, the command is
doing too much, not the docs.
New non-command sections: workspace layout (task and project), a
consolidated environment-variables table (previously scattered),
explicit query-resolution rules including archive-inclusive lookup
behavior, session modes (direct vs persistent), and a shell-completion
how-to.
Examples use the canonical "ctask" command name per spec §3 — docs
describe the product, not the user's local binary path.
Audit walked every cmd/ and internal/ file that produces user-facing
output. All command-form hints (text the user is meant to type back)
were already routed through invocationName() in v0.5.3 — the audit is
a verification pass, not a code rewrite.
Additions:
- Extract formatResumeRestoreHint and formatDirectModeTmuxHint as
testable string-only helpers. Production paths are unchanged
behaviorally; the helpers exist purely so the audit can pin down
the format strings without simulating tmux or stderr capture.
- Two new tests pinning the invocation name to a non-canonical value
("my-bin"). The pre-existing tests already protect these surfaces
but pin the name to "ctask", so they cannot detect a regression
that hard-codes "ctask" inside the format string. The new tests
flush that out for the resume restore hint and the Layer-1
active-session attach hint.
- Drop the duplicated withInvocationName helper accidentally added in
the info-session tests; reuse the canonical helper from
persistent_test.go.
Product-identity references ("ctask persistent mode requires tmux",
the SSH-remote `ssh -t <host> ctask <subcmd>` hint, doctor's "[ctask]"
diagnostic prefix, root-command Use:/Long:) deliberately remain
literal per spec §2.
Add a SESSION column to ctask list output, inserted to the right of
STATUS per spec. Values: "direct", "persistent", "stale", or em dash
for no session. Populated by SessionStatus, so each workspace adds at
most one short lease-file read — negligible for typical workspace
counts.
Archived workspaces always render as the em dash regardless of any
lease file present. The spec calls this a display simplification, not
a lifecycle invariant: ctask info still surfaces the raw session
state on archived workspaces because info is the diagnostic command.
ctask list --names is unchanged: one basename per line, no header,
no SESSION column. Verified by a regression test that asserts every
emitted line is bare-basename whitespace-free and contains none of
the SESSION tokens.
Add a Session block to ctask info output, surfacing the workspace
session lease state derived from SessionStatus. Inserted between Path
and any launch-dir fields so the new content is visually distinct
from both blocks.
Format: state on the header line, then indented Mode / Owner / Attach
/ Note rows aligned at column 14. The Owner line omits the hostname
when it matches the local machine. The Attach hint surfaces only for
active+persistent sessions and uses invocationName() so the suggested
command reflects the user's actual invocation. Malformed leases
render as stale with a single-line diagnostic and no Mode/Owner/Attach
rows so we never display fields parsed from a broken file.
Exposes session.CurrentHostname() so the cmd layer has a single
source of truth for the local-vs-remote hostname check.
Add internal/session.SessionStatus(wsDir) that derives a display-only
view of the workspace session lease. Pure read of .ctask/session.json
with no tmux invocation, no PID liveness, no lock acquisition, and no
mutation of lease state.
States: none | active | stale. Mode defaults to "direct" when a
pre-v0.5.3 lease lacks the field. Malformed leases surface as stale
with a diagnostic so the present-but-broken case stays visible
instead of being silently classified as none.
Reused for ctask info and ctask list in subsequent commits. Lifecycle
code continues to use the existing primitives (ReadLease, IsFresh,
InspectLease).
Three independent v0.5.3 polish items surfaced during manual WSL smoke testing,
bundled into one commit since they're all string/UX touches with no behavior change.
1. v0.4 lease-prompt tightening (`internal/session/{lease,run,run_preflight}.go`,
`cmd/entry.go`): when ctask is about to enter direct mode on a workspace that
already has a live tmux session, the "Continue anyway?" prompt now suggests
`ctask attach <slug>` as the reattach path. Threaded via
`PreflightOpts.ActiveLeaseHint` / `LaunchOpts.ActiveLeaseHint`; computed in
`cmd/entry.go::directModeTmuxHint` (best-effort: silent when no tmux on PATH
or no session for the workspace). Closes the footgun where a user forgot to
`export CTASK_SESSION_MODE=persistent` in a second terminal and hit the v0.4
coexistence prompt without realizing tmux passive-reattach was the intended
path.
2. Invocation-name in user-facing command hints (`cmd/invocation.go` new,
`cmd/{persistent,entry,resume,doctor}.go`): the binary name printed in
bypass / restore / "create one with" suggestions now reflects
`filepath.Base(os.Args[0])` instead of a hard-coded "ctask". Local-build
PowerShell users running `.\ctask.exe` see `ctask.exe new <ws> --direct`,
matching what they need to type. Installed contexts continue to see `ctask`.
Test seam (`invocationNameOverride`) pins the name to "ctask" in unit tests
so substring assertions stay stable across Go test binary names. Descriptive
prose ("ctask persistent mode requires...") and the ssh-remote hint
(`ssh -t <host> ctask <subcmd>`) intentionally keep the literal "ctask" —
they refer to the program identity / remote invocation, not the local
command form. Affected tests: `cmd/{persistent,resume}_test.go` tightened to
check the full `"<binary> <subcmd> <workspace> --direct"` form.
3. Smoke-checklist fixes (`docs/.../2026-05-08-v0.5.3-smoke-test-checklist.md`):
six issues caught during the run -- S2 now exports CTASK_SESSION_MODE in
both terminals (previously only WSL-A had it, which routed WSL-B's
secondary resume through direct mode instead of passive reattach); O3/A2
tmux-ls expectations corrected (tmux doesn't emit a literal "(detached)"
token); P2 expected behavior rewritten (passive reattach detach returns to
prompt immediately -- AttachExisting calls only shell.AttachSession with
no PollSessionEnd, the owner is responsible for finalize); A1 no longer
asks for Ctrl-C in WSL-B; A6 path now uses a glob (was hardcoded to the
checklist's authoring date, broke on v0.5.1 local-time directory naming);
M1 PATH-hide rewritten to `$HOME/.local/bin` only (was `:/bin` which is a
symlink to /usr/bin on usrmerge systems, did not hide tmux) and uses
`command -v` instead of `which` (which is itself in /usr/bin, unreachable
under the minimal PATH); M3/M4 reordered so the no-workspace verification
runs after PATH is restored (was silently failing under minimal PATH);
T1 wording made "substring match" explicit; T2 wording made N/A
unambiguous; section 10 split into 10a-10f, each a separate input, to
work around PSReadLine multi-line paste parsing.
Add the v0.5.2 round summary (commits a5e508b..3b6be0d + 5910100):
restore/notes/path commands, direct-lookup archived-inclusive policy,
resume archived hint, list --names, shell completion, cross-workspace
context seed section. Windows + WSL validation passed; Linux binary
statically linked.
Add load-bearing v0.5.2 invariants to the "don't unlearn" section
(archived-inclusive lookup policy, list --names emits basenames not
slugs, completion calls ListWorkspaces directly, etc.). Replace the
"Next: v0.5.2" pointer with a "Next: v0.6 (planning)" stub covering
config/agent profile work, resume-error polish, and flag-aware
completion for open/delete --all.
Drop v0.5.2-spec.md from the untracked-files list (committed in a5e508b).
Adds a concise "## Cross-Workspace Context" section to both the
task and project CLAUDE.md seed templates. Teaches the agent to
inspect related workspaces with the new commands before making
changes:
ctask list --all discover all workspaces, including archived
ctask info <workspace> view metadata and status of any workspace
ctask notes <workspace> read another workspace's notes.md
ctask path <workspace> get the filesystem path to inspect files
Closes the v0.5.2 design loop: ctask exposes workspace context
through CLI commands and lets agents consume it themselves. The
seed text is read-only by convention — the section explicitly
asks the agent to treat other workspaces as read-only unless the
user grants modification rights.
Applies to newly created workspaces only. Existing workspaces
keep their current CLAUDE.md (per spec: no retroactive overwrite).
Users with custom seed directories see this only if they update
their seeds.
Adds a --names flag to ctask list that emits one workspace
directory basename per line, no header, no decoration. Empty
result is empty stdout with zero exit code (no "No workspaces
found." placeholder).
Used by shell completion scripts and external tooling. Candidates
are directory basenames rather than bare slugs because basenames
are unique under the resolver's exact-match step while slugs can
collide across categories or dates.
Respects existing list filters: --all, --task, --projects,
--category, --limit. So:
ctask list --names active workspaces only
ctask list --names --all active and archived
ctask list --names --projects active project workspaces
The new TestListNamesCandidatesResolveUniquely test enforces the
spec invariant: every line emitted by list --names must resolve
to exactly one workspace via the standard resolver.
Apply the v0.5.2 lookup policy to the existing commands and wire
ValidArgsFunction hooks across the workspace-accepting surface.
info: drop the --all/-a flag entirely. Direct lookup is now
archived-inclusive by default — the user typed a name, so we find
the workspace and surface its status in the output. The Status
line already distinguishes active vs archived clearly.
resume: when targeting an archived workspace, fail with a useful
hint instead of letting the resolver report "not found":
[ctask] error: workspace "X" is archived
To restore it:
ctask restore X
This is implemented by resolving archived-inclusive and rejecting
status==archived before any session-launch logic runs. Genuine
not-found and ambiguous-match behavior are unchanged.
Adds ValidArgsFunction hooks to archive (active), delete (active),
open (active), info (any), resume (active). Restore/notes/path
already have hooks from the previous commit. Shell completion now
covers the full direct-lookup surface.
Three new direct-lookup commands per v0.5.2-spec.md:
- ctask restore <ws> un-archive a workspace (metadata-only flip,
mirrors archive's lease guard, refuses to
restore an already-active workspace)
- ctask notes <ws> stream a workspace's notes.md to stdout (raw,
no framing, [ctask]-prefixed stderr on error)
so AI agents can read prior workspace context
through standard shell pipelines
- ctask path <ws> print the absolute filesystem path of a
workspace, OS-native separators, one line
All three resolve archived-inclusive: the user typed a name, so we
find the workspace whether or not it's archived. Listing stays
filtered (active-only by default) per the v0.5.2 design rule
"listing is filtered, direct lookup is comprehensive".
Adds shared completion infrastructure (cmd/completion.go) used by
these commands and wired into the existing workspace-accepting
commands in a follow-up commit. Candidates are workspace directory
basenames (e.g. 2026-04-22_promptvolley) rather than bare slugs
because basenames are unique under the resolver's exact-match step
while slugs can collide across categories or dates.
Update notes.md with the v0.5.1 Linux portability baseline (commits
7a7b249, 1033072): WSL-native validation passed, install.sh works,
ctask doctor recognizes the Linux statusline helper, the cross-built
Linux binary is statically linked, and WorkspacePath was removed from
new task.yaml metadata. Add load-bearing notes for the new invariants
(CGO_ENABLED=0, install script does not modify shell config) and a
"Next: v0.5.2" pointer.
Also check in v0.5.2-spec.md so the workspace-retrieval round has the
same on-disk durability as the prior specs.
A native Linux build of build-linux defaulted to CGO_ENABLED=1 and
produced a glibc-linked binary, which would not run in minimal
containers (Alpine, distroless, scratch). The Windows cross-compile
was already pure-Go because Go disables cgo when no host C toolchain
is available; making CGO_ENABLED=0 explicit keeps both targets
statically linked regardless of build host.
Verified on WSL: file reports "statically linked", ldd reports
"not a dynamic executable".
- justfile: add build-linux, build-windows, build-all (output to dist/)
- .gitignore: cover ctask, ctask-*, dist/
- scripts/install.sh + scripts/uninstall.sh: POSIX equivalents of .ps1
- remove WorkspacePath metadata field (no production readers; legacy
task.yaml files continue to parse silently)
Linux smoke-test on WSL/container pending.
See audit-report.md and v0.5.1-spec.md.
Workspace directory names (YYYY-MM-DD_slug) and the YYYYMMDD-HHMMSS ID
field now use local time so users see their wall-clock date rather
than UTC — the prior behavior caused evening-EST creations to appear
under tomorrow's date for several hours every day. ctask info's
Created/Updated/Archived lines also convert to local for display.
Stored timestamps in task.yaml, session logs, the lease, the manifest,
and the session summary all continue to use UTC. Only user-facing
surfaces change.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds the workspace-layout diagram to the --project section, describes
how launch_dir is set and overridden, and documents the v0.5 rules for
fallback (missing/not-a-dir) and error (absolute/escape). Adds
CTASK_LAUNCH_DIR to the env-vars table and CTASK_PROJECT_ROOT INFO line
to the doctor example. Query Resolution note explains that both
CTASK_ROOT and the default projects/ subdirectory are searched so
default-location projects are findable from any shell.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Both .sh and .ps1 now build an effective display path by joining
CTASK_WORKSPACE with CTASK_LAUNCH_DIR when that variable is set. When
launch_dir is present and differs from the slug, the project tag also
carries ':<launch_dir>' so the display reflects user-overridden
launches. Tasks and pre-v0.5 projects are unchanged.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Rewrites the built-in project CLAUDE.md template with a new Workspace
Structure section that explains the root-vs-subdir split. File
Placement rules refer to the subdirectory. Git section keeps the
single-repo rule and explicitly names the project subdirectory as an
example of where not to init.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Three-state check matching the seed-dir pattern: INFO when unset
(points at the default discovery location), INFO with user-scope
advisory when set and present, FAIL when set but the directory
doesn't exist. Advisory wording is recommendatory, not prescriptive
(per spec amendment).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
When CTASK_PROJECT_ROOT is unset, SearchRoots now appends
\$CTASK_ROOT/projects/ so that projects created under the default
category are discoverable from any shell without per-session env var
setup. Dedupe in scanAllRoots prevents double-counting workspaces that
are reachable both via the depth-2 scan under CTASK_ROOT and via the
new explicit search root. Adds a named regression test asserting no
duplicates appear in either ResolveQuery or ListWorkspaces results.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
For project workspaces with launch_dir set, info prints three extra
lines after Path: Launch dir, Launch path, and Dir exists (yes/no
from a direct os.Stat of the intended path). Tasks and pre-v0.5
projects still omit these lines.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
LaunchOpts gains LaunchDir. session.Run resolves it via
workspace.ResolveLaunch, prints any fallback warning, and passes the
absolute path as the child process's working directory. Security
violations (absolute paths, .. escape) abort the session. The banner
gains a 'project dir: <name>/' line when launch_dir is set.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
typebasedio