Improve list-jobs output

Author: rorylshanks

cmd/partforge/main.go

@@ -2191,13 +2191,17 @@ func runListJobs(ctx context.Context, args []string) error {
 }
 
 func buildListJobsOutput(jobs []state.Job) listJobsOutput {
-	out := listJobsOutput{Jobs: make([]string, 0, len(jobs))}
+	out := listJobsOutput{
+		Jobs:    make([]string, 0, len(jobs)),
+		Details: make([]listJobDetail, 0, len(jobs)),
+	}
 	jobNames := map[string]string{}
 	for _, job := range jobs {
 		out.Jobs = append(out.Jobs, job.JobID)
 		if job.Name != "" {
 			jobNames[job.JobID] = job.Name
 		}
+		out.Details = append(out.Details, buildListJobDetail(job))
 	}
 	if len(jobNames) > 0 {
 		out.JobNames = jobNames
@@ -2206,13 +2210,58 @@ func buildListJobsOutput(jobs []state.Job) listJobsOutput {
 }
 
 func printJobs(out *os.File, jobs []state.Job) {
+	tw := tabwriter.NewWriter(out, 0, 0, 2, ' ', 0)
+	fmt.Fprintln(tw, "JOB_ID\tSTATUS\tPARTS\tREWRITE\tIMPORT\tSUBMITTED_AT\tUPDATED_AT\tNAME\tCOUNTS")
 	for _, job := range jobs {
-		if job.Name == "" {
-			fmt.Fprintln(out, job.JobID)
+		detail := buildListJobDetail(job)
+		fmt.Fprintf(
+			tw,
+			"%s\t%s\t%d\t%s\t%s\t%s\t%s\t%s\t%s\n",
+			detail.JobID,
+			detail.Status,
+			detail.PartsTotal,
+			formatListJobProgress(detail.RewriteCompleted, detail.PartsTotal),
+			formatListJobProgress(detail.ImportCompleted, detail.PartsTotal),
+			detail.SubmittedAt,
+			detail.UpdatedAt,
+			detail.Name,
+			formatStatusCounts(detail.StatusCounts),
+		)
+	}
+	_ = tw.Flush()
+}
+
+func buildListJobDetail(job state.Job) listJobDetail {
+	rewriteCompleted := job.Counts[state.StatusCompactReady] + job.Counts[state.StatusCompacting] + job.Counts[state.StatusSuperseded] + job.Counts[state.StatusFinished] + job.Counts[state.StatusImporting] + job.Counts[state.StatusImported]
+	importCompleted := job.Counts[state.StatusImported]
+	return listJobDetail{
+		JobID:            job.JobID,
+		Name:             job.Name,
+		Status:           overallStatus(job.Total, job.Counts),
+		PartsTotal:       job.Total,
+		RewriteCompleted: rewriteCompleted,
+		RewritePercent:   percent(rewriteCompleted, job.Total),
+		ImportCompleted:  importCompleted,
+		ImportPercent:    percent(importCompleted, job.Total),
+		SubmittedAt:      job.SubmittedAt,
+		UpdatedAt:        job.UpdatedAt,
+		StatusCounts:     listJobStatusCounts(job.Counts),
+	}
+}
+
+func listJobStatusCounts(counts map[state.Status]int) []statusCount {
+	out := make([]statusCount, 0, len(statusOrder()))
+	for _, status := range statusOrder() {
+		if counts[status] == 0 {
 			continue
 		}
-		fmt.Fprintf(out, "%s\t%s\n", job.JobID, job.Name)
+		out = append(out, statusCount{Status: status, Count: counts[status]})
 	}
+	return out
+}
+
+func formatListJobProgress(done, total int) string {
+	return fmt.Sprintf("%d/%d %.1f%%", done, total, percent(done, total))
 }
 
 func runJobStatus(ctx context.Context, args []string) error {
@@ -3439,6 +3488,21 @@ type jobStatusOutput struct {
 type listJobsOutput struct {
 	Jobs     []string          `json:"jobs"`
 	JobNames map[string]string `json:"job_names,omitempty"`
+	Details  []listJobDetail   `json:"job_details"`
+}
+
+type listJobDetail struct {
+	JobID            string        `json:"job_id"`
+	Name             string        `json:"name,omitempty"`
+	Status           string        `json:"status"`
+	PartsTotal       int           `json:"parts_total"`
+	RewriteCompleted int           `json:"rewrite_completed"`
+	RewritePercent   float64       `json:"rewrite_percent"`
+	ImportCompleted  int           `json:"import_completed"`
+	ImportPercent    float64       `json:"import_percent"`
+	SubmittedAt      string        `json:"submitted_at,omitempty"`
+	UpdatedAt        string        `json:"updated_at,omitempty"`
+	StatusCounts     []statusCount `json:"status_counts,omitempty"`
 }
 
 type retryFailedOutput struct {

cmd/partforge/main_test.go

@@ -1449,20 +1449,49 @@ func TestPrintJobSummaryHumanizesBytes(t *testing.T) {
 func TestPrintJobsIncludesNames(t *testing.T) {
 	got := captureFileOutput(t, func(out *os.File) {
 		printJobs(out, []state.Job{
-			{JobID: "job-a", Name: "Backfill A"},
-			{JobID: "job-b"},
+			{
+				JobID:       "job-a",
+				Name:        "Backfill A",
+				Total:       3,
+				Counts:      map[state.Status]int{state.StatusReady: 2, state.StatusFinished: 1},
+				SubmittedAt: "2026-06-24T00:00:00.000000000Z",
+				UpdatedAt:   "2026-06-24T01:00:00.000000000Z",
+			},
+			{JobID: "job-b", Total: 1, Counts: map[state.Status]int{state.StatusFailed: 1}},
 		})
 	})
 
-	if got != "job-a\tBackfill A\njob-b\n" {
-		t.Fatalf("printJobs output = %q", got)
+	for _, want := range []string{
+		"JOB_ID",
+		"STATUS",
+		"PARTS",
+		"SUBMITTED_AT",
+		"UPDATED_AT",
+		"COUNTS",
+		"job-a",
+		"Backfill A",
+		"READY",
+		"READY=2, FINISHED=1",
+		"job-b",
+		"FAILED",
+	} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("printJobs output missing %q:\n%s", want, got)
+		}
 	}
 }
 
 func TestBuildListJobsOutputPreservesJobIDList(t *testing.T) {
 	got := buildListJobsOutput([]state.Job{
-		{JobID: "job-a", Name: "Backfill A"},
-		{JobID: "job-b"},
+		{
+			JobID:       "job-a",
+			Name:        "Backfill A",
+			Total:       3,
+			Counts:      map[state.Status]int{state.StatusFinished: 2, state.StatusImported: 1},
+			SubmittedAt: "2026-06-24T00:00:00.000000000Z",
+			UpdatedAt:   "2026-06-24T01:00:00.000000000Z",
+		},
+		{JobID: "job-b", Total: 1, Counts: map[state.Status]int{state.StatusReady: 1}},
 	})
 
 	if strings.Join(got.Jobs, ",") != "job-a,job-b" {
@@ -1471,6 +1500,15 @@ func TestBuildListJobsOutputPreservesJobIDList(t *testing.T) {
 	if len(got.JobNames) != 1 || got.JobNames["job-a"] != "Backfill A" {
 		t.Fatalf("job names = %+v", got.JobNames)
 	}
+	if len(got.Details) != 2 {
+		t.Fatalf("job details = %+v", got.Details)
+	}
+	if got.Details[0].Status != "READY_FOR_IMPORT" || got.Details[0].PartsTotal != 3 || got.Details[0].RewriteCompleted != 3 || got.Details[0].ImportCompleted != 1 || got.Details[0].SubmittedAt == "" || got.Details[0].UpdatedAt == "" {
+		t.Fatalf("job-a detail = %+v", got.Details[0])
+	}
+	if got.Details[1].Status != "READY" || got.Details[1].PartsTotal != 1 {
+		t.Fatalf("job-b detail = %+v", got.Details[1])
+	}
 }
 
 func TestPrintJobSummaryIncludesInProgressStages(t *testing.T) {

docs/dynamodb.md

@@ -3,7 +3,7 @@
 PartForge tracks every part of every job as a row in a single DynamoDB table. This is the source of truth for the pipeline: workers claim work with conditional updates, transition parts through their lifecycle, and record progress and compaction lineage here. Because all state lives in DynamoDB, jobs are resumable and can be driven by many workers at once.
 
 The table holds no bulk data — only per-part metadata and pointers to the S3 artifacts. Part data itself lives in S3.
-Rows may include `job_name` when `upload-freeze -job-name` is used; `list-jobs` displays it with the job ID.
+Rows may include `job_name` when `upload-freeze -job-name` is used; `list-jobs` displays it with job status, counts, and timestamps.
 
 ## Schema
 

docs/operations.md

@@ -34,11 +34,11 @@ Workers also write a per-part progress heartbeat to DynamoDB every `15s` (`-stat
 ## Inspecting jobs
 
 ```sh
-partforge list-jobs                 # job IDs and optional names in the state table (uses the gsi1 index)
+partforge list-jobs                 # jobs with status, part counts, submitted/updated timestamps, optional names (uses the gsi1 index)
 partforge job-status -job-id=job-123
 ```
 
-Both accept `-json`; `list-jobs -json` keeps `jobs` as job IDs and adds `job_names` when names are set. `job-status -parts` adds per-row detail (persisted rewrite counters, compact-ready age, destination partitions, active part stats, `FAILED_MERGES`); `job-status -details` adds each part's current stage and per-stage timings. The physical part counters (`input_clickhouse_parts`, `current_output_clickhouse_parts`) refer to ClickHouse parts, not state rows.
+Both accept `-json`; `list-jobs -json` keeps `jobs` as job IDs, adds `job_names` when names are set, and includes `job_details` for status/progress/timestamps. `job-status -parts` adds per-row detail (persisted rewrite counters, compact-ready age, destination partitions, active part stats, `FAILED_MERGES`); `job-status -details` adds each part's current stage and per-stage timings. The physical part counters (`input_clickhouse_parts`, `current_output_clickhouse_parts`) refer to ClickHouse parts, not state rows.
 
 ## Admin and recovery commands
 

e2e/run.sh

@@ -186,7 +186,7 @@ job_list="$(
     list-jobs \
     -dynamodb-endpoint=http://localstack:4566
 )"
-if ! grep -F $'e2e-job\tE2E import' <<<"$job_list" >/dev/null; then
+if ! grep -F "E2E import" <<<"$job_list" >/dev/null; then
   echo "list-jobs did not include job name; output:" >&2
   echo "$job_list" >&2
   exit 1

internal/state/dynamo.go

@@ -125,8 +125,12 @@ type Part struct {
 }
 
 type Job struct {
-	JobID string `json:"job_id"`
-	Name  string `json:"name,omitempty"`
+	JobID       string         `json:"job_id"`
+	Name        string         `json:"name,omitempty"`
+	Total       int            `json:"total"`
+	Counts      map[Status]int `json:"counts,omitempty"`
+	SubmittedAt string         `json:"submitted_at,omitempty"`
+	UpdatedAt   string         `json:"updated_at,omitempty"`
 }
 
 type QueryProgress struct {
@@ -1427,11 +1431,13 @@ func (s *Store) ListJobsByStatus(ctx context.Context, statuses ...Status) ([]Job
 			TableName:              aws.String(s.table),
 			IndexName:              aws.String(readyIndexName),
 			KeyConditionExpression: aws.String("#gsi1pk = :status"),
-			ProjectionExpression:   aws.String("#job_id, #job_name"),
+			ProjectionExpression:   aws.String("#job_id, #job_name, #created_at, #updated_at"),
 			ExpressionAttributeNames: map[string]string{
-				"#gsi1pk":   "gsi1pk",
-				"#job_id":   "job_id",
-				"#job_name": "job_name",
+				"#gsi1pk":     "gsi1pk",
+				"#job_id":     "job_id",
+				"#job_name":   "job_name",
+				"#created_at": "created_at",
+				"#updated_at": "updated_at",
 			},
 			ExpressionAttributeValues: map[string]types.AttributeValue{
 				":status": stringAttr(statusKey(status)),
@@ -1460,19 +1466,33 @@ func (s *Store) ListJobsByStatus(ctx context.Context, statuses ...Status) ([]Job
 				if err != nil {
 					return nil, err
 				}
+				createdAt, err := optionalStringAttr(item, "created_at")
+				if err != nil {
+					return nil, err
+				}
+				updatedAt, err := optionalStringAttr(item, "updated_at")
+				if err != nil {
+					return nil, err
+				}
 				existing := jobsByID[value.Value]
 				if existing.JobID == "" {
-					jobsByID[value.Value] = Job{JobID: value.Value, Name: name}
-					continue
+					existing = Job{JobID: value.Value, Name: name, Counts: map[Status]int{}}
 				}
 				if existing.Name == "" && name != "" {
 					existing.Name = name
-					jobsByID[value.Value] = existing
-					continue
 				}
 				if existing.Name != "" && name != "" && existing.Name != name {
 					return nil, fmt.Errorf("job %s has conflicting job_name values %q and %q", value.Value, existing.Name, name)
 				}
+				existing.Total++
+				existing.Counts[status]++
+				if createdAt != "" && (existing.SubmittedAt == "" || createdAt < existing.SubmittedAt) {
+					existing.SubmittedAt = createdAt
+				}
+				if updatedAt != "" && updatedAt > existing.UpdatedAt {
+					existing.UpdatedAt = updatedAt
+				}
+				jobsByID[value.Value] = existing
 			}
 		}
 	}

internal/state/dynamo_test.go

@@ -162,9 +162,9 @@ func TestListJobsByStatusReturnsNames(t *testing.T) {
 		w.Header().Set("Content-Type", "application/x-amz-json-1.0")
 		switch {
 		case strings.Contains(string(body), statusKey(StatusReady)):
-			_, _ = io.WriteString(w, `{"Items":[{"job_id":{"S":"job-b"},"job_name":{"S":"Backfill B"}},{"job_id":{"S":"job-a"}}]}`)
+			_, _ = io.WriteString(w, `{"Items":[{"job_id":{"S":"job-b"},"job_name":{"S":"Backfill B"},"created_at":{"S":"2026-06-24T00:05:00.000000000Z"},"updated_at":{"S":"2026-06-24T00:10:00.000000000Z"}},{"job_id":{"S":"job-a"},"created_at":{"S":"2026-06-24T00:02:00.000000000Z"},"updated_at":{"S":"2026-06-24T00:03:00.000000000Z"}}]}`)
 		case strings.Contains(string(body), statusKey(StatusFailed)):
-			_, _ = io.WriteString(w, `{"Items":[{"job_id":{"S":"job-a"},"job_name":{"S":"Backfill A"}}]}`)
+			_, _ = io.WriteString(w, `{"Items":[{"job_id":{"S":"job-a"},"job_name":{"S":"Backfill A"},"created_at":{"S":"2026-06-24T00:01:00.000000000Z"},"updated_at":{"S":"2026-06-24T00:20:00.000000000Z"}}]}`)
 		default:
 			t.Errorf("request body missing expected status: %s", string(body))
 			_, _ = io.WriteString(w, `{"Items":[]}`)
@@ -188,6 +188,12 @@ func TestListJobsByStatusReturnsNames(t *testing.T) {
 	if len(got) != 2 || got[0].JobID != "job-a" || got[0].Name != "Backfill A" || got[1].JobID != "job-b" || got[1].Name != "Backfill B" {
 		t.Fatalf("jobs = %+v, want sorted jobs with names", got)
 	}
+	if got[0].Total != 2 || got[0].Counts[StatusReady] != 1 || got[0].Counts[StatusFailed] != 1 || got[0].SubmittedAt != "2026-06-24T00:01:00.000000000Z" || got[0].UpdatedAt != "2026-06-24T00:20:00.000000000Z" {
+		t.Fatalf("job-a summary = %+v", got[0])
+	}
+	if got[1].Total != 1 || got[1].Counts[StatusReady] != 1 || got[1].SubmittedAt != "2026-06-24T00:05:00.000000000Z" || got[1].UpdatedAt != "2026-06-24T00:10:00.000000000Z" {
+		t.Fatalf("job-b summary = %+v", got[1])
+	}
 }
 
 func TestSelectCompactBatchPartsAllowsSingleMultiPartArtifact(t *testing.T) {